Creazione di gestori di estensione della shell

Le funzionalità di Shell possono essere estese con voci del Registro di sistema e file di .ini. Anche se questo approccio per estendere shell è semplice e adeguato per molti scopi, è limitato. Ad esempio, se si usa il Registro di sistema per specificare un'icona personalizzata per un tipo di file, verrà visualizzata la stessa icona per ogni file di tale tipo. L'estensione della shell con il Registro di sistema non consente di variare l'icona per file diversi dello stesso tipo. Non è possibile modificare altri aspetti della shell, ad esempio il foglio proprietà Proprietà che può essere visualizzato quando un file viene fatto clic con il pulsante destro del mouse, non può essere modificato con il Registro di sistema.

Un approccio più potente e flessibile per estendere shell consiste nell'implementare gestori di estensioni della shell. Questi gestori possono essere implementati per un'ampia gamma di azioni che la Shell può eseguire. Prima di eseguire l'azione, Shell esegue una query sul gestore dell'estensione, offrendo la possibilità di modificare l'azione. Un esempio comune è un gestore dell'estensione del menu di scelta rapida. Se viene implementato per un tipo di file, verrà eseguita una query ogni volta che viene fatto clic con il pulsante destro del mouse su uno dei file. Il gestore può quindi specificare voci di menu aggiuntive in base a file in base al file anziché avere lo stesso set per l'intero tipo di file.

Questo documento illustra come implementare i gestori di estensione che consentono di modificare un'ampia gamma di azioni shell. I gestori seguenti sono associati a un tipo di file specifico e consentono di specificare in base a un file per file:

Altri gestori non sono associati a un tipo di file specifico, ma vengono chiamati prima di alcune operazioni di Shell:

I dettagli su come implementare gestori di estensione specifici sono illustrati nelle sezioni elencate sopra. Il resto di questo documento illustra alcuni problemi di implementazione comuni a tutti i gestori di estensioni shell.

• Implementazione dei gestori di estensioni shell
  • Implementazione di IPersistFile
  • Implementazione di IShellExtInit
  • Personalizzazione della descrizione info
• Miglioramento di Windows Search con gestori di estensioni shell
• Registrazione dei gestori di estensioni shell
  • Nomi del gestore
  • Oggetti Shell predefiniti
  • Esempio di registrazione del gestore estensioni
• Argomenti correlati

Implementazione dei gestori di estensioni shell

Gran parte dell'implementazione di un oggetto gestore estensioni shell dipende dal relativo tipo. Esistono tuttavia alcuni elementi comuni. In questa sezione vengono illustrati gli aspetti dell'implementazione condivisi da tutti i gestori di estensioni shell.

Molti gestori di estensioni shell sono oggetti COM (Component Object Model) in-process. Devono essere assegnati un GUID e registrati come descritto in Registrazione dei gestori di estensioni shell. Vengono implementati come DLL e devono esportare le funzioni standard seguenti:

• DllMain. Punto di ingresso standard alla DLL.
• DllGetClassObject. Espone la class factory dell'oggetto.
• DllCanUnloadNow. COM chiama questa funzione per determinare se l'oggetto serve tutti i client. In caso contrario, il sistema può scaricare la DLL e liberare la memoria associata.

Come tutti gli oggetti COM, i gestori di estensione shell devono implementare un'interfaccia IUnknown e una classe factory. La maggior parte dei gestori di estensione deve anche implementare un'interfaccia IPersistFile o IShellExtInit in Windows XP o versioni precedenti. Questi sono stati sostituiti da IInitializeWithStream, IInitializeWithItem e IInitializeWithFile in Windows Vista. Shell usa queste interfacce per inizializzare il gestore.

L'interfaccia IPersistFile deve essere implementata dal codice seguente:

• Gestori dati
• Gestori di rilascio

In passato, i gestori dell'icona erano necessari anche per implementare IPersistFile, ma questo non è più vero. Per i gestori delle icone, iPersistFile è ora facoltativo e altre interfacce come IInitializeWithItem sono preferite.

L'interfaccia IShellExtInit deve essere implementata dal codice seguente:

• Gestori di menu di scelta rapida
• Gestori trascinatori di trascinamento
• Gestori foglio delle proprietà

Implementazione di IPersistFile

L'interfaccia IPersistFile è destinata a consentire il caricamento di un oggetto da o salvato in un file disco. Ha sei metodi oltre a IUnknown, cinque dei propri e il metodo GetClassID che eredita da IPersist. Con le estensioni shell, IPersist viene usato solo per inizializzare un oggetto gestore di estensione shell. Poiché in genere non è necessario leggere o scrivere sul disco, solo i metodi GetClassID e Load richiedono un'implementazione nonken.

Shell chiama prima GetClassID e la funzione restituisce l'identificatore di classe (CLSID) dell'oggetto gestore di estensione. Shell chiama quindi Load e passa due valori. Il primo, pszFileName, è una stringa Unicode con il nome del file o della cartella su cui Shell sta per operare. Il secondo è dwMode, che indica la modalità di accesso ai file. Poiché in genere non è necessario accedere ai file, dwMode è in genere zero. Il metodo archivia questi valori in base alle esigenze per riferimento successivo.

Il frammento di codice seguente illustra come un gestore di estensioni shell tipico implementa i metodi GetClassID e Load . È progettato per gestire ANSI o Unicode. CLSID_SampleExtHandler è il GUID dell'oggetto gestore di estensione e CSampleExtHandler è il nome della classe usata per implementare l'interfaccia. Le variabili m_szFileName e m_dwMode sono variabili private usate per archiviare il nome e i flag di accesso del file.

wchar_t m_szFileName[MAX_PATH];    // The file name
DWORD m_dwMode;                  // The file access mode

CSampleExtHandler::GetClassID(CLSID *pCLSID)
{
    *pCLSID = CLSID_SampleExtHandler;
}

CSampleExtHandler::Load(PCWSTR pszFile, DWORD dwMode)
{
    m_dwMode = dwMode;
    return StringCchCopy(_szFileName, ARRAYSIZE(m_szFileName), pszFile);
}

Implementazione di IShellExtInit

L'interfaccia IShellExtInit ha un solo metodo , IShellExtInit::Initialize, oltre a IUnknown. Il metodo dispone di tre parametri che shell può usare per passare vari tipi di informazioni. I valori passati dipendono dal tipo di gestore e alcuni possono essere impostati su NULL.

• pIDFolder contiene il puntatore di una cartella a un elenco di identificatori di elemento (PIDL). Per le estensioni della finestra delle proprietà, è NULL. Per le estensioni del menu di scelta rapida, si tratta del PIDL della cartella che contiene l'elemento il cui menu di scelta rapida viene visualizzato. Per i gestori di trascinamento e rilascio non predefiniti, è il CODICE PIDL della cartella di destinazione.
• pDataObject contiene un puntatore all'interfaccia IDataObject di un oggetto dati. L'oggetto dati contiene uno o più nomi di file nel formato CF_HDROP .
• hRegKey contiene una chiave del Registro di sistema per l'oggetto file o il tipo di cartella.

Il metodo IShellExtInit::Initialize archivia il nome file, il puntatore IDataObject e la chiave del Registro di sistema in base alle esigenze per un uso successivo. Il frammento di codice seguente illustra un'implementazione di IShellExtInit::Initialize. Per semplicità, in questo esempio si presuppone che l'oggetto dati contenga solo un singolo file. In generale, potrebbe contenere più file che dovranno essere estratti.

LPCITEMIDLIST  m_pIDFolder;           //The folder's PIDL
wchar_t        m_szFile[MAX_PATH];    //The file name
IDataObject   *m_pDataObj;            //The IDataObject pointer
HKEY           m_hRegKey;             //The file or folder's registry key

STDMETHODIMP CShellExt::Initialize(LPCITEMIDLIST pIDFolder, 
                                   IDataObject *pDataObj, 
                                   HKEY hRegKey) 
{ 
    // If Initialize has already been called, release the old PIDL
    ILFree(m_pIDFolder);
    m_pIDFolder = nullptr;

    // Store the new PIDL.
    if (pIDFolder)
    {
        m_pIDFolder = ILClone(pIDFolder);
    }
    
    // If Initialize has already been called, release the old
    // IDataObject pointer.
    if (m_pDataObj)
    { 
        m_pDataObj->Release(); 
    }
     
    // If a data object pointer was passed in, save it and
    // extract the file name. 
    if (pDataObj) 
    { 
        m_pDataObj = pDataObj; 
        pDataObj->AddRef(); 
      
        STGMEDIUM   medium;
        FORMATETC   fe = {CF_HDROP, NULL, DVASPECT_CONTENT, -1, TYMED_HGLOBAL};
        UINT        uCount;

        if (SUCCEEDED(m_pDataObj->GetData(&fe, &medium)))
        {
            // Get the count of files dropped.
            uCount = DragQueryFile((HDROP)medium.hGlobal, (UINT)-1, NULL, 0);

            // Get the first file name from the CF_HDROP.
            if (uCount)
                DragQueryFile((HDROP)medium.hGlobal, 0, m_szFile, 
                              sizeof(m_szFile)/sizeof(TCHAR));

            ReleaseStgMedium(&medium);
        }
    }

    // Duplicate the registry handle. 
    if (hRegKey) 
        RegOpenKeyEx(hRegKey, nullptr, 0L, MAXIMUM_ALLOWED, &m_hRegKey); 
    return S_OK; 
}

CSampleExtHandler è il nome della classe usata per implementare l'interfaccia. Le variabili m_pIDFolder, m_pDataObject, m_szFileName e m_hRegKey sono variabili private usate per archiviare le informazioni passate. Per semplicità, in questo esempio si presuppone che l'oggetto dati conterrà un solo nome di file. Dopo aver recuperato la struttura FORMATETC dall'oggetto dati, DragQueryFile viene utilizzato per estrarre il nome del file dal membro medium.hGlobal della struttura FORMATETC. Se viene passata una chiave del Registro di sistema, il metodo usa RegOpenKeyEx per aprire la chiave e assegna l'handle a m_hRegKey.

Personalizzazione della descrizione informazioni

Esistono due modi per personalizzare le descrizioni info:

• Implementare un oggetto che supporta IQueryInfo e quindi registrare l'oggetto nella sottochiave appropriata nel Registro di sistema (vedere Registrazione di gestori estensioni shell di seguito).
• Specificare una stringa fissa o un elenco di proprietà di file specifiche da visualizzare.

Per visualizzare una stringa fissa per un'estensione dello spazio dei nomi, creare una voce denominata InfoTip nella chiave {CLSID} dell'estensione dello spazio dei nomi. Impostare il valore di tale voce come stringa letterale da visualizzare, come illustrato in questo esempio, o una stringa indiretta che specifica una risorsa e un indice all'interno di tale risorsa (a scopo di localizzazione).

HKEY_CLASSES_ROOT
   CLSID
      {CLSID}
         InfoTip = InfoTip string for your namespace extension

Per visualizzare una stringa fissa per un tipo di file, creare una voce denominata InfoTip nella chiave ProgID di tale tipo di file. Impostare il valore di tale voce come stringa letterale da visualizzare o una stringa indiretta che specifica una risorsa e un indice all'interno di tale risorsa (a scopo di localizzazione), come illustrato in questo esempio.

HKEY_CLASSES_ROOT
   ProgID
      InfoTip = Resource.dll, 3

Se si desidera che shell visualizzi proprietà di file specifiche nella descrizione info per un tipo di file specifico, creare una voce denominata InfoTip nella chiave ProgID per tale tipo di file. Impostare il valore di tale voce in modo che sia un elenco delimitato da punto e virgola di nomi di proprietà canonici, coppie di identificatori di formato (FMTID)/identificatore di proprietà (PID) o entrambe. Questo valore deve iniziare con "prop:" per identificarlo come stringa dell'elenco di proprietà. Se si omette "prop:", il valore viene visualizzato come stringa letterale e visualizzato come tale.

Nell'esempio seguente propname è un nome di proprietà canonico (ad esempio System.Date) e {fmtid}, pid è una coppia FMTID/PID .

HKEY_CLASSES_ROOT
   ProgID
      InfoTip = prop:propname;propname;{fmtid},pid;{fmtid},pid

È possibile usare i nomi di proprietà seguenti:

Miglioramento di Windows Search con gestori di estensioni della shell

I gestori di estensione della shell possono essere usati per migliorare l'esperienza utente fornita da un gestore del protocollo di Windows Search. Per abilitare tali miglioramenti, il gestore dell'estensione shell di supporto deve essere progettato per l'integrazione con il gestore del protocollo di ricerca come origine dati. Per informazioni su come migliorare un gestore di protocolli di Windows Search tramite l'integrazione con un gestore di estensioni shell, vedere Aggiunta di icone, anteprime e menu di scelta rapida. Per altre informazioni sui gestori di protocollo di Windows Search, vedere Sviluppo di gestori di protocollo.

Registrazione dei gestori di estensioni della shell

Prima di poterlo usare, è necessario registrare un oggetto gestore dell'estensione shell. Questa sezione descrive in generale come registrare un gestore di estensioni shell.

Ogni volta che si crea o si modifica un gestore di estensioni shell, è importante notificare al sistema che è stata apportata una modifica con SHChangeNotify, specificando l'evento SHCNE_ASSOCCHANGED . Se non si chiama SHChangeNotify, la modifica potrebbe non essere riconosciuta fino al riavvio del sistema.

Come per tutti gli oggetti COM, è necessario creare un GUID per il gestore usando uno strumento come UUIDGEN.exe. Creare una chiave in HKEY_CLASSES_ROOT\CLSID il cui nome è il formato stringa del GUID. Poiché i gestori di estensione della shell sono server in-process, è necessario creare una chiave InProcServer32 nella chiave GUID con il valore predefinito impostato sul percorso della DLL del gestore. Usare il modello di threading Apartment.

Ogni volta che shell esegue un'azione che può coinvolgere un gestore di estensioni shell, controlla la chiave del Registro di sistema appropriata. La chiave in cui viene registrato un gestore di estensione controlla quindi quando verrà chiamata. Ad esempio, è pratica comune avere un gestore di menu di scelta rapida chiamato quando shell visualizza un menu di scelta rapida per un membro di un tipo di file. In questo caso, il gestore deve essere registrato nella chiave ProgID del tipo di file.

Nomi dei gestori

Per abilitare un gestore dell'estensione shell, creare una sottochiave con il nome della sottochiave del gestore (vedere di seguito) nella sottochiave ShellEx di ProgID (per i tipi di file) o il nome del tipo di oggetto Shell (per Oggetti shell predefiniti).

Ad esempio, se si vuole registrare un gestore di estensione del menu di scelta rapida per MyProgram.1, si inizierà creando la sottochiave seguente:

HKEY_CLASSES_ROOT
   MyProgram.1
      ShellEx
         ContextMenuHandlers

Per i gestori seguenti, creare una sottochiave sotto la chiave "Handler Subkey name" il cui nome è la versione stringa del CLSID dell'estensione Shell. È possibile registrare più estensioni nella chiave del nome della sottochiave del gestore creando più sottochiavi.

Per i gestori seguenti, il valore predefinito della chiave "Handler Subkey Name" è la versione stringa del CLSID dell'estensione Shell. È possibile registrare una sola estensione per questi gestori.

Le sottochiavi specificate per aggiungere Aggiungi al menu Start e Aggiungi alla barra delle applicazioni alla barra delle applicazioni sono necessarie solo per i tipi di file che includono la voce IsShortCut .

Il supporto per i gestori del provider di colonne è stato rimosso in Windows Vista. Inoltre, a partire da Windows Vista, IPropertySetStorage è stato deprecato a favore di IPropertyStore.

Mentre IExtractImage rimane supportato, IThumbnailProvider è preferito per Windows Vista e versioni successive.

Oggetti Shell predefiniti

Shell definisce oggetti aggiuntivi in HKEY_CLASSES_ROOT che possono essere estesi nello stesso modo dei tipi di file. Ad esempio, per aggiungere un gestore del foglio delle proprietà per tutti i file, è possibile registrare nella chiave PropertySheetHandlers .

HKEY_CLASSES_ROOT
   *
      shellex
         PropertySheetHandlers

La tabella seguente fornisce le varie sottochiavi di HKEY_CLASSES_ROOT in cui è possibile registrare i gestori di estensione. Si noti che molti gestori di estensione non possono essere registrati in tutte le sottochiave elencate. Per altre informazioni, vedere la documentazione del gestore specifico.

Note:

• Il menu di scelta rapida in background della cartella file è accessibile facendo clic con il pulsante destro del mouse all'interno di una cartella file, ma non tramite alcun contenuto della cartella.
• "Verbi" sono comandi speciali registrati in HKEY_CLASSES_ROOT\Subkey\Shell\Verb .
• PerTipo direte\ , "#" è un codice di tipo \# provider di rete in decimale. Il codice del tipo di provider di rete è la parola alta di un tipo di rete. L'elenco dei tipi di rete viene specificato nel file di intestazione Winnetwk.h (valori WNNC_NET_*). Ad esempio, WNNC_NET_SHIVA è 0x00330000, quindi la chiave di tipo corrispondente sarà HKEY_CLASSES_ROOT\tipo di\rete\51 .
• "network_provider_name" è un nome del provider di rete specificato da WNetGetProviderName, con gli spazi convertiti in caratteri di sottolineatura. Ad esempio, se il provider di rete Microsoft è installato, il nome del provider è "Microsoft Windows Network" e il network_provider_name corrispondente è Microsoft_Windows_Network.

Esempio di registrazione del gestore estensioni

Per abilitare un determinato gestore, creare una sottochiave nella chiave del tipo di gestore dell'estensione con il nome del gestore. Shell non usa il nome del gestore, ma deve essere diverso da tutti gli altri nomi sotto tale sottochiave. Impostare il valore predefinito della sottochiave nome sulla forma stringa del GUID del gestore.

Nell'esempio seguente vengono illustrate le voci del Registro di sistema che abilitano i gestori di estensioni del menu di scelta rapida e del foglio delle proprietà, usando un esempio di tipo di file .myp:

HKEY_CLASSES_ROOT
   .myp
      (Default) = MyProgram.1
   CLSID
      {00000000-1111-2222-3333-444444444444}
         InProcServer32
            (Default) = C:\MyDir\MyCommand.dll
            ThreadingModel = Apartment
      {11111111-2222-3333-4444-555555555555}
         InProcServer32
            (Default) = C:\MyDir\MyPropSheet.dll
            ThreadingModel = Apartment
   MyProgram.1
      (Default) = MyProgram Application
      Shellex
         ContextMenuHandler
            MyCommand
               (Default) = {00000000-1111-2222-3333-444444444444}
         PropertySheetHandlers
            MyPropSheet
               (Default) = {11111111-2222-3333-4444-555555555555}

La procedura di registrazione descritta in questa sezione deve essere seguita per tutti i sistemi Windows.

Argomenti correlati

Linee guida per l'implementazione di estensioni In-Process