diff --git a/README.md b/README.md index b8eab52..a8837a3 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,50 @@ # UniversalShellExt -Shell Extension COM generica per Windows che aggiunge una voce personalizzabile al menu contestuale di cartelle. +Generic COM Shell Extension for Windows that adds a customizable entry to the folder context menu. -## Funzionalità +## Features -- ✅ **Menu Contestuale Personalizzabile**: - - Voce nel menu contestuale per cartelle (click destro su cartella) - - Voce nel menu contestuale per sfondo cartella (click destro su area vuota) - - Testo, icona e comando completamente configurabili via registro -- ✅ **Configurazione Flessibile**: - - Tutti i parametri letti dal registro di Windows - - Supporto per argomenti personalizzati con placeholder `%1` - - Icona estratta automaticamente dall'eseguibile -- ✅ **Sicurezza e Compatibilità**: - - Supporto UAC elevation automatico se necessario - - Compatibile con Windows 10/11 (x64) - - Accesso registro WOW64 corretto (64-bit) +- ✅ **Customizable Context Menu**: + - Context menu entry for folders (right-click on folder) + - Context menu entry for folder background (right-click on empty area) + - Text, icon and command fully configurable via registry +- ✅ **Flexible Configuration**: + - All parameters read from the Windows registry + - Support for custom arguments with `%1` placeholder + - Icon automatically extracted from the executable +- ✅ **Security and Compatibility**: + - Automatic UAC elevation support when required + - Compatible with Windows 10/11 (x64) + - Correct WOW64 registry access (64-bit) - Thread-safe -## File del Progetto +## Project Files -| File | Descrizione | +| File | Description | |------|-------------| -| `UniversalShellExt.cpp` | Codice sorgente C++ della Shell Extension COM | -| `UniversalShellExt.def` | Definizioni esportazioni DLL | -| `UniversalShellExt.rc` | Risorse della DLL (Version Info) | -| `build.py` | Script Python per compilazione, firma e registrazione | +| `UniversalShellExt.cpp` | C++ source code of the COM Shell Extension | +| `UniversalShellExt.def` | DLL export definitions | +| `UniversalShellExt.rc` | DLL resources (Version Info) | +| `build.py` | Python script for build, signing and registration | -## Configurazione +## Configuration -La DLL legge la configurazione dal registro di Windows: +The DLL reads its configuration from the Windows registry: -### Chiavi di Registro +### Registry Keys -**Percorso:** `HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt` +**Path:** `HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt` *(Fallback: `HKEY_CURRENT_USER\SOFTWARE\UniversalShellExt`)* -| Valore | Tipo | Descrizione | Esempio | -|--------|------|-------------|---------| -| `Command` | REG_SZ | Percorso completo dell'eseguibile | `N:\VSCode.exe` | -| `Arguments` | REG_SZ | Argomenti da passare (`%1` = path selezionato) | `"%1"` | -| `MenuText` | REG_SZ | Testo visualizzato nel menu | `Apri con VSCode` | -| `Icon` | REG_SZ | Percorso icona (exe o ico) | `N:\VSCode.exe` | +| Value | Type | Description | Example | +|-------|------|-------------|---------| +| `Command` | REG_SZ | Full path to the executable | `N:\VSCode.exe` | +| `Arguments` | REG_SZ | Arguments to pass (`%1` = selected path) | `"%1"` | +| `MenuText` | REG_SZ | Text displayed in the menu | `Open with VSCode` | +| `Icon` | REG_SZ | Icon path (exe or ico) | `N:\VSCode.exe` | -### Template Configurazione +### Configuration Template ```reg Windows Registry Editor Version 5.00 @@ -52,120 +52,120 @@ Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt] "Command"="N:\\VSCode.exe" "Arguments"="\"%1\"" -"MenuText"="Apri con VSCode Portable" +"MenuText"="Open with VSCode Portable" "Icon"="N:\\VSCode.exe" ``` -### Valori Default +### Default Values -Se non configurati: -- `Arguments` → `"%1"` (passa il percorso selezionato) +If not configured: +- `Arguments` → `"%1"` (passes the selected path) - `MenuText` → `"Open with Application"` -- `Icon` → usa lo stesso percorso di `Command` +- `Icon` → uses the same path as `Command` -## Identificatori +## Identifiers -| Tipo | Valore | -|------|--------| +| Type | Value | +|------|-------| | **CLSID** | `{5D849F86-F2A9-41FA-8A24-E01CD6D6696C}` | -| **Nome COM** | `Universal Portable Shell Extension` | +| **COM Name** | `Universal Portable Shell Extension` | -## Compilazione +## Build -### Prerequisiti -- **Visual Studio 2022** (con workload "Desktop development with C++") -- **Windows SDK** (per `signtool.exe` e `rc.exe`) +### Prerequisites +- **Visual Studio 2022** (with "Desktop development with C++" workload) +- **Windows SDK** (for `signtool.exe` and `rc.exe`) - **Python 3.x** -- **Certificato di firma** (opzionale, per firma digitale) +- **Signing certificate** (optional, for digital signing) ### Build Script ```powershell -# Build completo (compila, copia, firma, registra) +# Full build (compile, copy, sign, register) python build.py -# Solo pulizia +# Clean only python build.py --clean -# Solo deregistrazione +# Unregister only python build.py --unregister -# Build senza firma +# Build without signing python build.py --no-sign ``` ### Output -La DLL compilata viene copiata in: +The compiled DLL is copied to: ``` plugins\UniversalShellExt64.dll ``` -## Registrazione +## Registration -### Metodo Consigliato (tramite Launcher) +### Recommended Method (via Launcher) -Il launcher `VSCode.exe` gestisce automaticamente la registrazione: +The `VSCode.exe` launcher automatically manages registration: ```powershell -N:\VSCode.exe /register # Registra la shell extension -N:\VSCode.exe /unregister # Rimuove la shell extension -N:\VSCode.exe /register /silent # Modalità silenziosa +N:\VSCode.exe /register # Register the shell extension +N:\VSCode.exe /unregister # Remove the shell extension +N:\VSCode.exe /register /silent # Silent mode ``` -### Metodo Manuale (regsvr32) +### Manual Method (regsvr32) -Eseguire come **Amministratore**: +Run as **Administrator**: ```cmd -:: Registrazione -regsvr32 "N:\Code\Workspace\Launchers\plugins\UniversalShellExt64.dll" - -:: Rimozione -regsvr32 /u "N:\Code\Workspace\Launchers\plugins\UniversalShellExt64.dll" +regsvr32 "plugins\UniversalShellExt64.dll" ``` -## Chiavi di Registro Create +## Registry Keys Created -Durante la registrazione (`DllRegisterServer`): +During registration (`DllRegisterServer`): -| Chiave | Scopo | -|--------|-------| -| `HKCR\CLSID\{5D849F86-...}` | Registrazione classe COM | -| `HKCR\CLSID\{5D849F86-...}\InprocServer32` | Percorso DLL | -| `HKCR\Directory\shellex\ContextMenuHandlers\UniversalShellExt` | Handler per cartelle | -| `HKCR\Directory\Background\shellex\ContextMenuHandlers\...` | Handler per sfondo | -| `HKLM\...\Shell Extensions\Approved` | Whitelist Microsoft | +| Key | Purpose | +|-----|---------| +| `HKCR\CLSID\{5D849F86-...}` | COM class registration | +| `HKCR\CLSID\{5D849F86-...}\InprocServer32` | DLL path | +| `HKCR\Directory\shellex\ContextMenuHandlers\UniversalShellExt` | Handler for folders | +| `HKCR\Directory\Background\shellex\ContextMenuHandlers\...` | Handler for folder background | +| `HKLM\...\Shell Extensions\Approved` | Microsoft whitelist | -## Come Funziona +## How It Works -1. **Inizializzazione**: Quando l'utente fa click destro, Explorer carica la DLL -2. **Configurazione**: La DLL legge `Command`, `Arguments`, `MenuText`, `Icon` dal registro -3. **Menu**: Inserisce la voce nel menu contestuale con l'icona configurata -4. **Esecuzione**: Al click, sostituisce `%1` con il percorso e lancia il comando -5. **UAC**: Se il comando richiede elevazione, la richiede automaticamente +1. **Initialization**: When the user right-clicks, Explorer loads the DLL +2. **Configuration**: The DLL reads `Command`, `Arguments`, `MenuText`, `Icon` from the registry +3. **Menu**: Inserts the entry in the context menu with the configured icon +4. **Execution**: On click, replaces `%1` with the path and launches the command +5. **UAC**: If the command requires elevation, requests it automatically ## Troubleshooting -### La voce non appare nel menu -1. Verificare che la DLL sia registrata (`regsvr32`) -2. Controllare che le chiavi di registro siano configurate -3. Riavviare Explorer (`taskkill /F /IM explorer.exe && explorer.exe`) +### Entry does not appear in the menu +1. Verify the DLL is registered (`regsvr32`) +2. Check that the registry keys are configured +3. Restart Explorer (`taskkill /F /IM explorer.exe && explorer.exe`) -### Errore di registrazione -- Eseguire come Amministratore -- Verificare che la DLL sia firmata (Windows potrebbe bloccare DLL non firmate) +### Registration error +- Run as Administrator +- Verify the DLL is signed (Windows may block unsigned DLLs) -### Il comando non viene eseguito -- Verificare il percorso in `Command` sia corretto -- Controllare che `Arguments` contenga `%1` per ricevere il percorso +### Command is not executed +- Verify the path in `Command` is correct +- Check that `Arguments` contains `%1` to receive the path -## Versioni +## Versions -| Versione | Note | -|----------|------| -| **1.0.0** | Prima release - Shell extension generica configurabile via registro | +| Version | Notes | +|---------|-------| +| **1.0.0** | First release — generic shell extension configurable via registry | -## Licenza +## License -Uso interno - emulab.it +Internal use — emulab.it + +--- + +*See [README_IT.md](README_IT.md) for the Italian version.* diff --git a/README_IT.md b/README_IT.md new file mode 100644 index 0000000..b8eab52 --- /dev/null +++ b/README_IT.md @@ -0,0 +1,171 @@ +# UniversalShellExt + +Shell Extension COM generica per Windows che aggiunge una voce personalizzabile al menu contestuale di cartelle. + +## Funzionalità + +- ✅ **Menu Contestuale Personalizzabile**: + - Voce nel menu contestuale per cartelle (click destro su cartella) + - Voce nel menu contestuale per sfondo cartella (click destro su area vuota) + - Testo, icona e comando completamente configurabili via registro +- ✅ **Configurazione Flessibile**: + - Tutti i parametri letti dal registro di Windows + - Supporto per argomenti personalizzati con placeholder `%1` + - Icona estratta automaticamente dall'eseguibile +- ✅ **Sicurezza e Compatibilità**: + - Supporto UAC elevation automatico se necessario + - Compatibile con Windows 10/11 (x64) + - Accesso registro WOW64 corretto (64-bit) + - Thread-safe + +## File del Progetto + +| File | Descrizione | +|------|-------------| +| `UniversalShellExt.cpp` | Codice sorgente C++ della Shell Extension COM | +| `UniversalShellExt.def` | Definizioni esportazioni DLL | +| `UniversalShellExt.rc` | Risorse della DLL (Version Info) | +| `build.py` | Script Python per compilazione, firma e registrazione | + +## Configurazione + +La DLL legge la configurazione dal registro di Windows: + +### Chiavi di Registro + +**Percorso:** `HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt` + +*(Fallback: `HKEY_CURRENT_USER\SOFTWARE\UniversalShellExt`)* + +| Valore | Tipo | Descrizione | Esempio | +|--------|------|-------------|---------| +| `Command` | REG_SZ | Percorso completo dell'eseguibile | `N:\VSCode.exe` | +| `Arguments` | REG_SZ | Argomenti da passare (`%1` = path selezionato) | `"%1"` | +| `MenuText` | REG_SZ | Testo visualizzato nel menu | `Apri con VSCode` | +| `Icon` | REG_SZ | Percorso icona (exe o ico) | `N:\VSCode.exe` | + +### Template Configurazione + +```reg +Windows Registry Editor Version 5.00 + +[HKEY_LOCAL_MACHINE\SOFTWARE\UniversalShellExt] +"Command"="N:\\VSCode.exe" +"Arguments"="\"%1\"" +"MenuText"="Apri con VSCode Portable" +"Icon"="N:\\VSCode.exe" +``` + +### Valori Default + +Se non configurati: +- `Arguments` → `"%1"` (passa il percorso selezionato) +- `MenuText` → `"Open with Application"` +- `Icon` → usa lo stesso percorso di `Command` + +## Identificatori + +| Tipo | Valore | +|------|--------| +| **CLSID** | `{5D849F86-F2A9-41FA-8A24-E01CD6D6696C}` | +| **Nome COM** | `Universal Portable Shell Extension` | + +## Compilazione + +### Prerequisiti +- **Visual Studio 2022** (con workload "Desktop development with C++") +- **Windows SDK** (per `signtool.exe` e `rc.exe`) +- **Python 3.x** +- **Certificato di firma** (opzionale, per firma digitale) + +### Build Script + +```powershell +# Build completo (compila, copia, firma, registra) +python build.py + +# Solo pulizia +python build.py --clean + +# Solo deregistrazione +python build.py --unregister + +# Build senza firma +python build.py --no-sign +``` + +### Output + +La DLL compilata viene copiata in: +``` +plugins\UniversalShellExt64.dll +``` + +## Registrazione + +### Metodo Consigliato (tramite Launcher) + +Il launcher `VSCode.exe` gestisce automaticamente la registrazione: + +```powershell +N:\VSCode.exe /register # Registra la shell extension +N:\VSCode.exe /unregister # Rimuove la shell extension +N:\VSCode.exe /register /silent # Modalità silenziosa +``` + +### Metodo Manuale (regsvr32) + +Eseguire come **Amministratore**: + +```cmd +:: Registrazione +regsvr32 "N:\Code\Workspace\Launchers\plugins\UniversalShellExt64.dll" + +:: Rimozione +regsvr32 /u "N:\Code\Workspace\Launchers\plugins\UniversalShellExt64.dll" +``` + +## Chiavi di Registro Create + +Durante la registrazione (`DllRegisterServer`): + +| Chiave | Scopo | +|--------|-------| +| `HKCR\CLSID\{5D849F86-...}` | Registrazione classe COM | +| `HKCR\CLSID\{5D849F86-...}\InprocServer32` | Percorso DLL | +| `HKCR\Directory\shellex\ContextMenuHandlers\UniversalShellExt` | Handler per cartelle | +| `HKCR\Directory\Background\shellex\ContextMenuHandlers\...` | Handler per sfondo | +| `HKLM\...\Shell Extensions\Approved` | Whitelist Microsoft | + +## Come Funziona + +1. **Inizializzazione**: Quando l'utente fa click destro, Explorer carica la DLL +2. **Configurazione**: La DLL legge `Command`, `Arguments`, `MenuText`, `Icon` dal registro +3. **Menu**: Inserisce la voce nel menu contestuale con l'icona configurata +4. **Esecuzione**: Al click, sostituisce `%1` con il percorso e lancia il comando +5. **UAC**: Se il comando richiede elevazione, la richiede automaticamente + +## Troubleshooting + +### La voce non appare nel menu +1. Verificare che la DLL sia registrata (`regsvr32`) +2. Controllare che le chiavi di registro siano configurate +3. Riavviare Explorer (`taskkill /F /IM explorer.exe && explorer.exe`) + +### Errore di registrazione +- Eseguire come Amministratore +- Verificare che la DLL sia firmata (Windows potrebbe bloccare DLL non firmate) + +### Il comando non viene eseguito +- Verificare il percorso in `Command` sia corretto +- Controllare che `Arguments` contenga `%1` per ricevere il percorso + +## Versioni + +| Versione | Note | +|----------|------| +| **1.0.0** | Prima release - Shell extension generica configurabile via registro | + +## Licenza + +Uso interno - emulab.it