sdbtool 0.3.0__tar.gz

sdbtool-0.3.0/.github/workflows/python-test.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    runs-on: windows-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install the latest version of uv and set the python version
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Test with python ${{ matrix.python-version }}
+        run: uv run --frozen pytest

sdbtool-0.3.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env

sdbtool-0.3.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mark Jansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sdbtool-0.3.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: sdbtool
+Version: 0.3.0
+Summary: Dump SDB file to xml using apphelp.dll
+Project-URL: Homepage, https://pypi.org/project/sdbtool/
+Project-URL: Changelog, https://github.com/learn-more/sdbtool/releases
+Project-URL: Issues, https://github.com/learn-more/sdbtool/issues
+Project-URL: CI, https://github.com/learn-more/sdbtool/actions
+Project-URL: Repository, https://github.com/learn-more/sdbtool
+Author-email: Mark Jansen <mark.jansen@reactos.org>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: appcompat,apphelp,sdb,sdb2xml,sdbtool,shim,shimeng
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.2.1
+Description-Content-Type: text/markdown
+
+# sdbtool
+
+A tool for converting Microsoft Application Compatibility Database (SDB) files to XML format.
+
+## Table of Contents
+
+1. [Features](#features)
+1. [Getting Started](#getting-started)
+1. [Contributing](#contributing)
+1. [License](#license)
+
+## Features<a id="features"></a>
+
+- Parses SDB files used by Windows for application compatibility.
+- Converts SDB data into readable XML.
+- Useful for analysis, migration, or documentation.
+
+
+## Getting Started<a id="getting-started"></a>
+
+### Installation
+
+Sdbtool is available as [`sdbtool`](https://pypi.org/project/sdbtool/) on PyPI.
+
+Invoke sdbtool directly with [`uvx`](https://docs.astral.sh/uv/):
+
+```shell
+uvx sdbtool your.sdb                    # Convert the file 'your.sdb' to xml, and print it to the console
+uvx sdbtool your.sdb --output your.xml  # Convert the file 'your.sdb' to xml, and write it to 'your.xml'
+```
+
+Or install sdbtool with `uv` (recommended), `pip`, or `pipx`:
+
+```shell
+# With uv.
+uv tool install sdbtool@latest  # Install sdbtool globally.
+
+# With pip.
+pip install sdbtool
+
+# With pipx.
+pipx install sdbtool
+```
+
+## Contributing<a id="contributing"></a>
+
+Contributions are welcome! Please open issues or submit pull requests.
+
+## License<a id="license"></a>
+
+This project is licensed under the MIT License.

sdbtool-0.3.0/README.md

@@ -0,0 +1,51 @@
+# sdbtool
+
+A tool for converting Microsoft Application Compatibility Database (SDB) files to XML format.
+
+## Table of Contents
+
+1. [Features](#features)
+1. [Getting Started](#getting-started)
+1. [Contributing](#contributing)
+1. [License](#license)
+
+## Features<a id="features"></a>
+
+- Parses SDB files used by Windows for application compatibility.
+- Converts SDB data into readable XML.
+- Useful for analysis, migration, or documentation.
+
+
+## Getting Started<a id="getting-started"></a>
+
+### Installation
+
+Sdbtool is available as [`sdbtool`](https://pypi.org/project/sdbtool/) on PyPI.
+
+Invoke sdbtool directly with [`uvx`](https://docs.astral.sh/uv/):
+
+```shell
+uvx sdbtool your.sdb                    # Convert the file 'your.sdb' to xml, and print it to the console
+uvx sdbtool your.sdb --output your.xml  # Convert the file 'your.sdb' to xml, and write it to 'your.xml'
+```
+
+Or install sdbtool with `uv` (recommended), `pip`, or `pipx`:
+
+```shell
+# With uv.
+uv tool install sdbtool@latest  # Install sdbtool globally.
+
+# With pip.
+pip install sdbtool
+
+# With pipx.
+pipx install sdbtool
+```
+
+## Contributing<a id="contributing"></a>
+
+Contributions are welcome! Please open issues or submit pull requests.
+
+## License<a id="license"></a>
+
+This project is licensed under the MIT License.

sdbtool-0.3.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "sdbtool"
+version = "0.3.0"
+description = "Dump SDB file to xml using apphelp.dll"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Mark Jansen", email = "mark.jansen@reactos.org" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.2.1",
+]
+keywords = ["sdb", "sdbtool", "sdb2xml", "shim", "apphelp", "appcompat", "shimeng"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Operating System :: Microsoft :: Windows",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/sdbtool/"
+Changelog = "https://github.com/learn-more/sdbtool/releases"
+Issues = "https://github.com/learn-more/sdbtool/issues"
+CI = "https://github.com/learn-more/sdbtool/actions"
+Repository = "https://github.com/learn-more/sdbtool"
+
+[project.scripts]
+sdbtool = "sdbtool.cli:cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  ".vscode",
+  ".python-version",
+  "uv.lock",
+  "tests"
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+]
+

sdbtool-0.3.0/sdbtool/__init__.py

@@ -0,0 +1,131 @@
+'''
+PROJECT:     sdbtool
+LICENSE:     MIT (https://spdx.org/licenses/MIT)
+PURPOSE:     Entrypoint of the sdbtool tool, which converts SDB files to XML format.
+COPYRIGHT:   Copyright 2025 Mark Jansen <mark.jansen@reactos.org>
+'''
+import sdbtool.apphelp as apphelp
+from base64 import b64encode
+from xml.sax.saxutils import escape
+
+INDENT_DEPTH = 2
+
+def tagtype_to_xmltype(tag_type: int) -> str|None:
+    switch = {
+        apphelp.TAG_TYPE_BYTE: "xs:byte",
+        apphelp.TAG_TYPE_WORD: "xs:unsignedShort",
+        apphelp.TAG_TYPE_DWORD: "xs:unsignedInt",
+        apphelp.TAG_TYPE_QWORD: "xs:unsignedLong",
+        apphelp.TAG_TYPE_STRINGREF: "xs:string",
+        apphelp.TAG_TYPE_STRING: "xs:string",
+        apphelp.TAG_TYPE_BINARY: "xs:base64Binary",
+    }
+    return switch.get(tag_type, None)
+
+class Xml:
+    def __init__(self, stream, name, indent, attrib=None, xmltag=False):
+        self._stream = stream
+        self.name = name
+        self.indent = indent
+        self.attrib = attrib or {}
+        self._has_children = False
+        self._xmltag = xmltag
+        self._delay = None
+        self._closed = False
+
+    def node(self, name, attrib=None):
+        self._has_children = True
+        return Xml(self._stream, name, self.indent + 1, attrib)
+
+    def flush(self):
+        if self._delay:
+            self._stream.write(self._delay)
+            self._delay = None
+
+    def write(self, text):
+        self.flush()
+        self._stream.write(text)
+
+    def close(self):
+        assert self._delay is not None, "Xml.close() called when tag has content"
+        self._stream.write(" />")
+        self._delay = None
+        self._closed = True
+
+    def __enter__(self):
+        if self._xmltag:
+            self.write('<?xml version="1.0" encoding="utf-8" standalone="yes"?>')
+            self._xmltag = False
+        self.write("\n")
+        if self.indent:
+            self.write(" " * (self.indent*INDENT_DEPTH))
+        self.write(f"<{self.name}")
+        for key, value in self.attrib.items():
+            self.write(f' {key}="{value}"')
+
+        self._delay = ">"
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        if self._closed:
+            return
+        if self._has_children:
+            self.write("\n")
+            if self.indent:
+                self.write(" " * (self.indent*INDENT_DEPTH))
+        self.write(f"</{self.name}>")
+
+
+def dump_tag(node, tag):
+    if tag.type == apphelp.TAG_TYPE_LIST:
+        node.flush()
+        for childtag in tag.tags():
+            attrs = {}
+            if childtag.type != apphelp.TAG_TYPE_LIST and childtag.type != apphelp.TAG_TYPE_NULL:
+                typename = tagtype_to_xmltype(childtag.type)
+                assert typename is not None, f"Unknown tag type: {childtag.tag}"
+                attrs["type"] = typename
+            with node.node(childtag.name, attrs) as childnode:
+                dump_tag(childnode, childtag)
+        return
+
+    assert next(tag.tags(), None) is None, f"Tag {tag.name} is not a list but has children"
+
+    if tag.type == apphelp.TAG_TYPE_NULL:
+        node.close()
+    elif tag.type == apphelp.TAG_TYPE_BYTE:
+        node.write("<!-- UNHANDLED BYTE TAG, please report this at https://github.com/learn-more/sdbtool -->")
+    elif tag.type == apphelp.TAG_TYPE_WORD:
+        val = tag.as_word()
+        node.write(f"{val}")
+        if node.name in ("INDEX_TAG", "INDEX_KEY"):
+            node.write(f"<!-- {apphelp.tag_to_string(val)} -->")
+    elif tag.type == apphelp.TAG_TYPE_DWORD:
+        node.write(f"{tag.as_dword()}")
+    elif tag.type == apphelp.TAG_TYPE_QWORD:
+        node.write(f"{tag.as_qword()}")
+    elif tag.type in (apphelp.TAG_TYPE_STRINGREF, apphelp.TAG_TYPE_STRING):
+        val = escape(tag.as_string())
+        node.write(f"{val}")
+    elif tag.type == apphelp.TAG_TYPE_BINARY:
+        data = tag.as_bytes()
+        if not data:
+            node.close()
+        else:
+            base64_data = b64encode(data).decode('utf-8')
+            node.write(base64_data)
+    else:
+        raise ValueError(f"Unknown tag type: {tag.type} for tag {tag.name}")
+
+
+def convert(input_file: str, output_stream):
+    with apphelp.SdbDatabase(input_file, apphelp.PathType.DOS_PATH) as db:
+        if not db:
+            print(f"Failed to open database at '{input_file}'")
+            return
+        attrs = {
+            "xmlns:xs": "http://www.w3.org/2001/XMLSchema",
+            "path": input_file,
+        }
+        with Xml(output_stream, "SDB", 0, attrs, xmltag=True) as node:
+            dump_tag(node, db.root())

sdbtool-0.3.0/sdbtool/__main__.py

@@ -0,0 +1,4 @@
+from sdbtool.cli import cli
+
+if __name__ == "__main__":
+    cli()

sdbtool-0.3.0/sdbtool/apphelp.py

@@ -0,0 +1,174 @@
+'''
+PROJECT:     sdbtool
+LICENSE:     MIT (https://spdx.org/licenses/MIT)
+PURPOSE:     interface to the AppHelp API for reading SDB files.
+COPYRIGHT:   Copyright 2025 Mark Jansen <mark.jansen@reactos.org>
+'''
+from ctypes import windll, c_void_p, c_uint16, c_uint32, c_wchar_p, POINTER, c_ubyte, c_uint64
+from enum import IntEnum
+
+class PathType(IntEnum):
+    DOS_PATH = 0
+    NT_PATH = 1
+
+
+TAGID_NULL = 0x0
+TAGID_ROOT = 0x0
+_TAGID_ROOT = 12
+
+TAG_TYPE_MASK = 0xF000
+
+TAG_TYPE_NULL = 0x1000
+TAG_TYPE_BYTE = 0x2000
+TAG_TYPE_WORD = 0x3000
+TAG_TYPE_DWORD = 0x4000
+TAG_TYPE_QWORD = 0x5000
+TAG_TYPE_STRINGREF = 0x6000
+TAG_TYPE_LIST = 0x7000
+TAG_TYPE_STRING = 0x8000
+TAG_TYPE_BINARY = 0x9000
+TAG_NULL = 0x0
+
+
+APPHELP = windll.apphelp
+
+# PDB WINAPI SdbOpenDatabase(LPCWSTR path, PATH_TYPE type);
+APPHELP.SdbOpenDatabase.argtypes = [c_wchar_p, c_uint32]
+APPHELP.SdbOpenDatabase.restype = c_void_p
+
+# void WINAPI SdbCloseDatabase(PDB);
+APPHELP.SdbCloseDatabase.argtypes = [c_void_p]
+
+# TAGID WINAPI SdbGetFirstChild(PDB pdb, TAGID parent);
+APPHELP.SdbGetFirstChild.argtypes = [c_void_p, c_uint32]
+APPHELP.SdbGetFirstChild.restype = c_uint32
+
+# TAGID WINAPI SdbGetNextChild(PDB pdb, TAGID parent, TAGID prev_child);
+APPHELP.SdbGetNextChild.argtypes = [c_void_p, c_uint32, c_uint32]
+APPHELP.SdbGetNextChild.restype = c_uint32
+
+# TAG WINAPI SdbGetTagFromTagID(PDB pdb, TAGID tagid);
+APPHELP.SdbGetTagFromTagID.argtypes = [c_void_p, c_uint32]
+APPHELP.SdbGetTagFromTagID.restype = c_uint16
+
+# LPCWSTR WINAPI SdbTagToString(TAG tag);
+APPHELP.SdbTagToString.argtypes = [c_uint16]
+APPHELP.SdbTagToString.restype = c_wchar_p
+
+# WORD WINAPI SdbReadDWORDTag(PDB pdb, TAGID tagid, WORD ret);
+APPHELP.SdbReadWORDTag.argtypes = [c_void_p, c_uint32, c_uint16]
+APPHELP.SdbReadWORDTag.restype = c_uint16
+
+# DWORD WINAPI SdbReadDWORDTag(PDB pdb, TAGID tagid, DWORD ret);
+APPHELP.SdbReadDWORDTag.argtypes = [c_void_p, c_uint32, c_uint32]
+APPHELP.SdbReadDWORDTag.restype = c_uint32
+
+# QWORD WINAPI SdbReadQWORDTag(PDB pdb, TAGID tagid, QWORD ret);
+APPHELP.SdbReadQWORDTag.argtypes = [c_void_p, c_uint32, c_uint64]
+APPHELP.SdbReadQWORDTag.restype = c_uint64
+
+# DWORD WINAPI SdbGetTagDataSize(PDB pdb, TAGID tagid);
+APPHELP.SdbGetTagDataSize.argtypes = [c_void_p, c_uint32]
+APPHELP.SdbGetTagDataSize.restype = c_uint32
+
+# BOOL WINAPI SdbReadBinaryTag(PDB pdb, TAGID tagid, PBYTE buffer, DWORD size);
+APPHELP.SdbReadBinaryTag.argtypes = [c_void_p, c_uint32, POINTER(c_ubyte), c_uint32]
+APPHELP.SdbReadBinaryTag.restype = c_uint32
+
+# LPWSTR WINAPI SdbGetStringTagPtr(PDB pdb, TAGID tagid);
+APPHELP.SdbGetStringTagPtr.argtypes = [c_void_p, c_uint32]
+APPHELP.SdbGetStringTagPtr.restype = c_wchar_p
+
+def _get_tag_type(tag: int) -> int:
+    """Extracts the type from a tag."""
+    return tag & TAG_TYPE_MASK
+
+def tag_to_string(tag: int) -> str:
+    """Converts a tag to its string representation."""
+    return APPHELP.SdbTagToString(tag)
+
+class Tag:
+    def __init__(self, db: 'SdbDatabase', tag_id: int):
+        self.db = db
+        self.tag_id = tag_id
+        if tag_id == TAGID_ROOT:
+            self.tag = TAG_NULL
+            self.name = 'SDB'
+            self.type = TAG_TYPE_LIST
+        else:
+            self.tag = APPHELP.SdbGetTagFromTagID(db.handle, tag_id)
+            self.name = APPHELP.SdbTagToString(self.tag)
+            self.type = _get_tag_type(self.tag)
+
+    def tags(self):
+        child = APPHELP.SdbGetFirstChild(self.db.handle, self.tag_id)
+        while child != 0:
+            yield Tag(self.db, child)
+            child = APPHELP.SdbGetNextChild(self.db.handle, self.tag_id, child)
+
+    def as_word(self, default: int = 0) -> int:
+        """Returns the tag value as a word (16-bit integer)."""
+        if self.type != TAG_TYPE_WORD:
+            raise ValueError(f"Tag {self.name} is not a WORD type")
+        return APPHELP.SdbReadWORDTag(self.db.handle, self.tag_id, default)
+
+    def as_dword(self, default: int = 0) -> int:
+        """Returns the tag value as a dword (32-bit integer)."""
+        if self.type != TAG_TYPE_DWORD:
+            raise ValueError(f"Tag {self.name} is not a DWORD type")
+        return APPHELP.SdbReadDWORDTag(self.db.handle, self.tag_id, default)
+
+    def as_qword(self, default: int = 0) -> int:
+        """Returns the tag value as a qword (64-bit integer)."""
+        if self.type != TAG_TYPE_QWORD:
+            raise ValueError(f"Tag {self.name} is not a QWORD type")
+        return APPHELP.SdbReadQWORDTag(self.db.handle, self.tag_id, default)
+
+    def as_bytes(self) -> bytes:
+        """Returns the tag value as bytes."""
+        if self.type != TAG_TYPE_BINARY:
+            raise ValueError(f"Tag {self.name} is not a BINARY type")
+        size = APPHELP.SdbGetTagDataSize(self.db.handle, self.tag_id)
+        if size == 0:
+            return b''
+        data = (c_ubyte * size)()
+        result = APPHELP.SdbReadBinaryTag(self.db.handle, self.tag_id, data, size)
+        if result == 0:
+            raise ValueError(f"Failed to read binary tag {self.name}")
+        return bytes(data)
+
+    def as_string(self) -> str:
+        """Returns the tag value as a string."""
+        if self.type not in (TAG_TYPE_STRING, TAG_TYPE_STRINGREF):
+            raise ValueError(f"Tag {self.name} is not a STRING or STRINGREF type")
+        ptr = APPHELP.SdbGetStringTagPtr(self.db.handle, self.tag_id)
+        return ptr if ptr is not None else ''
+
+
+class SdbDatabase:
+    def __init__(self, path: str, path_type: PathType):
+        self.path = path
+        self.path_type = path_type
+        self.handle = APPHELP.SdbOpenDatabase(path, path_type)
+        self._root = None
+
+    def root(self):
+        if self._root is None and self.handle is not None:
+            self._root = Tag(self, TAGID_ROOT)
+        return self._root
+
+    def close(self):
+        if self.handle:
+            APPHELP.SdbCloseDatabase(self.handle)
+            self.handle = None
+
+    def __bool__(self):
+        if self.handle is None:
+            return False
+        return True
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()

sdbtool-0.3.0/sdbtool/cli.py

@@ -0,0 +1,14 @@
+from sdbtool import convert
+import click
+
+@click.command()
+@click.version_option()
+@click.argument("input_file", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "--output",
+    type=click.File("w", encoding="utf-8"),
+    default="-",
+    help="Path to the output XML file, or '-' for stdout.",
+)
+def cli(input_file, output):
+    convert(input_file, output)