APK File Handler: How WSA Installer Integrates with Windows Explorer

The Goal

APK files should feel like native Windows files — with custom icons, double-click functionality, and proper file associations. WSA Installer v1.2 makes this happen through Windows Registry integration and a COM-based shell extension.

Registry Integration

ProgID Registration

WSA Installer registers ProgIDs for 5 APK formats in the Windows Registry:

HKCR\WSAInstaller.apk
  @="APK File"
  FriendlyTypeName="@app.py,-100"

HKCR\WSAInstaller.apk\DefaultIcon
  @="C:\path\to\icon.ico"

HKCR\WSAInstaller.apk\shell\open\command
  @="\"C:\path\to\app.py\" --wsa-pacman \"%1\""

File Association

The ProgIDs are then associated with file extensions:

HKCR\.apk
  @="WSAInstaller.apk"

HKCR\.xapk
  @="WSAInstaller.xapk"

HKCR\.apks
  @="WSAInstaller.apks"

HKCR\.apkm
  @="WSAInstaller.apkm"

HKCR\.aab
  @="WSAInstaller.aab"

ApkIconShlExt.dll — Shell Extension

The ApkIconShlExt.dll is a COM-based shell extension that provides per-file icons in Windows Explorer. Instead of showing a generic file icon, each APK displays its own app icon.

COM Interfaces

The shell extension implements 4 COM interfaces:

• IExtractIconW — Provides the icon for the file
• IThumbnailProvider — Provides preview thumbnails
• IQueryInfo — Provides tooltip information
• IPersistFile — Allows the handler to load the file

Icon Extraction Process

• 1. Open APK file as ZIP archive
• 2. Search for icon files (res/mipmap-*/icon.png, res/drawable-*/icon.png)
• 3. Extract the highest-resolution icon
• 4. Convert to ICO format
• 5. Cache the extracted icon

Registration Process

During installation, WSA Installer registers the APK handler:

• 1. Copy ApkIconShlExt.dll to install directory
• 2. Register COM server in Registry
• 3. Register ProgIDs for all 5 formats
• 4. Set file associations
• 5. Update Explorer icon cache

REM Manual registration
app.py --register-apk

REM Manual unregistration
app.py --unregister-apk

Icon Watermarking

Desktop shortcuts created by WSA Pacman include a small watermark in the corner. This distinguishes WSA-installed apps from native Windows apps.

• Watermark is 16x16 pixels
• Placed in bottom-right corner
• Uses alpha blending for transparency
• Shows WSA Installer logo

Unregistration

When uninstalling WSA Installer, all Registry entries are cleaned up:

• Remove ProgIDs from HKCR
• Remove file associations
• Unregister COM server
• Delete ApkIconShlExt.dll
• Clear icon cache

Troubleshooting

Icons Not Showing

• Restart Explorer: `taskkill /f /im explorer.exe && explorer.exe`
• Clear icon cache: `ie4uinit.exe -show`
• Re-register DLL: `regsvr32 ApkIconShlExt.dll`

Double-Click Not Working

• Check file association: Right-click → Properties → Opens with
• Re-register handler: `app.py --register-apk`
• Check Registry entries with regedit