Criar Manipuladores de Extensão de Shell

Os recursos do Shell podem ser estendidos com entradas do Registro e arquivos .ini. Embora essa abordagem para estender o Shell seja simples e adequada para muitas finalidades, ela é limitada. Por exemplo, se você usar o Registro para especificar um ícone personalizado para um tipo de arquivo, o mesmo ícone aparecerá para cada arquivo desse tipo. Estender o Shell com o registro não permite que você varie o ícone para arquivos diferentes do mesmo tipo. Outros aspectos do Shell, como a folha de propriedades Propriedades que pode ser exibida quando um arquivo é clicado com o botão direito do mouse, não podem ser modificados com o registro.

Uma abordagem mais poderosa e flexível para estender o Shell é implementar manipuladores de extensão de shell. Esses manipuladores podem ser implementados para uma variedade de ações que o Shell pode executar. Antes de executar a ação, o Shell consulta o manipulador de extensão, dando a ele a oportunidade de modificar a ação. Um exemplo comum é um manipulador de extensão de menu de atalho. Se um for implementado para um tipo de arquivo, ele será consultado sempre que um dos arquivos for clicado com o botão direito do mouse. Em seguida, o manipulador pode especificar itens de menu adicionais em uma base arquivo a arquivo, em vez de ter o mesmo conjunto para todo o tipo de arquivo.

Este documento discute como implementar os manipuladores de extensão que permitem modificar uma variedade de ações do Shell. Os manipuladores a seguir são associados a um tipo de arquivo específico e permitem que você especifique em uma base arquivo a arquivo:

Outros manipuladores não estão associados a um tipo de arquivo específico, mas são chamados antes de algumas operações do Shell:

Os detalhes de como implementar manipuladores de extensão específicos são abordados nas seções listadas acima. O restante deste documento aborda alguns problemas de implementação comuns a todos os manipuladores de extensão do Shell.

• Implementando manipuladores de extensão do Shell
  • Implementando IPersistFile
  • Implementando IShellExtInit
  • Personalização do Infotip
• Aprimoramento da Pesquisa do Windows com manipuladores de extensão do Shell
• Registrando manipuladores de extensão de shell
  • Nomes de manipulador
  • Objetos shell predefinidos
  • Exemplo de um registro de manipulador de extensão
• Tópicos relacionados

Implementando manipuladores de extensão do Shell

Grande parte da implementação de um objeto de manipulador de extensão shell depende de seu tipo. Há, no entanto, alguns elementos comuns. Esta seção discute os aspectos da implementação que são compartilhados por todos os manipuladores de extensão do Shell.

Muitos manipuladores de extensão shell são objetos COM (Component Object Model) em processo. Eles devem ser atribuídos a um GUID e registrados conforme descrito em Registrando manipuladores de extensão do shell. Elas são implementadas como DLLs e devem exportar as seguintes funções padrão:

• DllMain. O ponto de entrada padrão para a DLL.
• DllGetClassObject. Expõe a fábrica de classes do objeto.
• DllCanUnloadNow. O COM chama essa função para determinar se o objeto está atendendo clientes. Caso contrário, o sistema pode descarregar a DLL e liberar a memória associada.

Como todos os objetos COM, os manipuladores de extensão do Shell devem implementar uma interface IUnknown e uma fábrica de classes. A maioria dos manipuladores de extensão também deve implementar uma interface IPersistFile ou IShellExtInit no Windows XP ou anterior. Eles foram substituídos por IInitializeWithStream, IInitializeWithItem e IInitializeWithFile no Windows Vista. O Shell usa essas interfaces para inicializar o manipulador.

A interface IPersistFile deve ser implementada pelo seguinte:

• Manipuladores de dados
• Remover manipuladores

No passado, manipuladores de ícone também eram necessários para implementar IPersistFile, mas isso não é mais verdade. Para manipuladores de ícones, IPersistFile agora é opcional e outras interfaces, como IInitializeWithItem , são preferenciais.

A interface IShellExtInit deve ser implementada pelo seguinte:

• Manipuladores de menu de atalho
• Manipuladores de arrastar e soltar
• Manipuladores de folha de propriedades

Implementando IPersistFile

A interface IPersistFile destina-se a permitir que um objeto seja carregado ou salvo em um arquivo de disco. Ele tem seis métodos além de IUnknown, cinco deles próprios e o método GetClassID que herda do IPersist. Com as extensões do Shell, o IPersist é usado apenas para inicializar um objeto de manipulador de extensão shell. Como normalmente não há necessidade de ler ou gravar no disco, somente os métodos GetClassID e Load exigem uma implementação nãontoken.

O Shell chama GetClassID primeiro e a função retorna o CLSID (identificador de classe) do objeto do manipulador de extensão. Em seguida, o Shell chama Load e passa dois valores. O primeiro, pszFileName, é uma cadeia de caracteres Unicode com o nome do arquivo ou pasta em que o Shell está prestes a operar. O segundo é dwMode, que indica o modo de acesso ao arquivo. Como normalmente não há necessidade de acessar arquivos, dwMode geralmente é zero. O método armazena esses valores conforme necessário para referência posterior.

O fragmento de código a seguir ilustra como um manipulador de extensão shell típico implementa os métodos GetClassID e Load . Ele foi projetado para lidar com ANSI ou Unicode. CLSID_SampleExtHandler é o GUID do objeto do manipulador de extensão e CSampleExtHandler é o nome da classe usada para implementar a interface. As variáveis m_szFileName e m_dwMode são variáveis privadas usadas para armazenar o nome do arquivo e os sinalizadores de acesso.

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);
}

Implementando IShellExtInit

A interface IShellExtInit tem apenas um método, IShellExtInit::Initialize, além de IUnknown. O método tem três parâmetros que o Shell pode usar para passar vários tipos de informações. Os valores passados dependem do tipo de manipulador e alguns podem ser definidos como NULL.

• pIDFolder contém o ponteiro de uma pasta para uma PIDL (lista de identificadores de item). Para extensões de folha de propriedades, é NULL. Para extensões de menu de atalho, é o PIDL da pasta que contém o item cujo menu de atalho está sendo exibido. Para manipuladores não padrão de arrastar e soltar, é o PIDL da pasta de destino.
• pDataObject mantém um ponteiro para a interface IDataObject de um objeto de dados. O objeto de dados contém um ou mais nomes de arquivo no formato CF_HDROP .
• hRegKey contém uma chave do Registro para o objeto de arquivo ou o tipo de pasta.

O método IShellExtInit::Initialize armazena o nome do arquivo, o ponteiro IDataObject e a chave do Registro conforme necessário para uso posterior. O fragmento de código a seguir ilustra uma implementação de IShellExtInit::Initialize. Para simplificar, este exemplo pressupõe que o objeto de dados contenha apenas um único arquivo. Em geral, ele pode conter vários arquivos que precisarão ser extraídos.

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 é o nome da classe usada para implementar a interface . As variáveis m_pIDFolder, m_pDataObject, m_szFileName e m_hRegKey são variáveis privadas usadas para armazenar as informações passadas. Para simplificar, este exemplo pressupõe que apenas um nome de arquivo será mantido pelo objeto de dados. Depois que a estrutura FORMATETC é recuperada do objeto de dados, DragQueryFile é usado para extrair o nome do arquivo do membro medium.hGlobal da estrutura FORMATETC. Se uma chave do Registro for passada, o método usará RegOpenKeyEx para abrir a chave e atribuirá o identificador a m_hRegKey.

Personalização da dica de informações

Há duas maneiras de personalizar dicas de informações:

• Implemente um objeto que dê suporte a IQueryInfo e registre esse objeto sob a subchave adequada no registro (consulte Registrando manipuladores de extensão do shell abaixo).
• Especifique uma cadeia de caracteres fixa ou uma lista de propriedades de arquivo específicas a serem exibidas.

Para exibir uma cadeia de caracteres fixa para uma extensão de namespace, crie uma entrada chamada InfoTip na chave {CLSID} da extensão de namespace. Defina o valor dessa entrada como a cadeia de caracteres literal que você deseja exibir, conforme mostrado neste exemplo, ou uma cadeia de caracteres indireta que especifica um recurso e um índice dentro desse recurso (para fins de localização).

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

Para exibir uma cadeia de caracteres fixa para um tipo de arquivo, crie uma entrada chamada InfoTip na chave ProgID desse tipo de arquivo. Defina o valor dessa entrada como a cadeia de caracteres literal que você deseja exibir ou uma cadeia de caracteres indireta que especifica um recurso e um índice dentro desse recurso (para fins de localização), conforme mostrado neste exemplo.

HKEY_CLASSES_ROOT
   ProgID
      InfoTip = Resource.dll, 3

Se você quiser que o Shell exiba propriedades de arquivo específicas na dica de informações para um tipo de arquivo específico, crie uma entrada chamada InfoTip na chave ProgID para esse tipo de arquivo. Defina o valor dessa entrada como uma lista delineada por ponto-e-vírgula de nomes de propriedade canônica, pares de IDENTIFICADOR de formato (FMTID)/PID (identificador de propriedade) ou ambos. Esse valor deve começar com "prop:" para identificá-lo como uma cadeia de caracteres de lista de propriedades. Se você omitir "prop:", o valor será visto como uma cadeia de caracteres literal e exibido como tal.

No exemplo a seguir, propname é um nome de propriedade canônica (como System.Date) e {fmtid},pid é um par FMTID/PID .

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

Os seguintes nomes de propriedade podem ser usados:

Aprimorando a Pesquisa do Windows com manipuladores de extensão do Shell

Os manipuladores de extensão do Shell podem ser usados para aprimorar a experiência do usuário fornecida por um manipulador de protocolo do Windows Search. Para habilitar esses aprimoramentos, o manipulador de extensão shell de suporte deve ser projetado para integrar-se ao manipulador de protocolo de pesquisa como uma fonte de dados. Para obter informações sobre como aprimorar um manipulador de protocolo do Windows Search por meio da integração com um manipulador de extensão do Shell, consulte Adicionando ícones, visualizações e menus de atalho. Para obter mais informações sobre manipuladores de protocolo do Windows Search, consulte Desenvolvendo manipuladores de protocolo.

Registrando manipuladores de extensão de shell

Um objeto de manipulador de extensão shell deve ser registrado antes que o Shell possa usá-lo. Esta seção é uma discussão geral sobre como registrar um manipulador de extensão do Shell.

Sempre que você cria ou altera um manipulador de extensão do Shell, é importante notificar o sistema de que você fez uma alteração com SHChangeNotify, especificando o evento SHCNE_ASSOCCHANGED . Se você não chamar SHChangeNotify, a alteração poderá não ser reconhecida até que o sistema seja reinicializado.

Assim como acontece com todos os objetos COM, você deve criar um GUID para o manipulador usando uma ferramenta como UUIDGEN.exe. Crie uma chave em HKEY_CLASSES_ROOT\CLSID cujo nome é a forma de cadeia de caracteres do GUID. Como os manipuladores de extensão do Shell são servidores em processo, você deve criar uma chave InProcServer32 sob a chave GUID com o valor padrão definido como o caminho da DLL do manipulador. Use o modelo de threading Apartment.

Sempre que o Shell executa uma ação que pode envolver um manipulador de extensão do Shell, ele verifica a chave do Registro apropriada. A chave sob a qual um manipulador de extensão é registrado controla, portanto, quando ele será chamado. Por exemplo, é uma prática comum ter um manipulador de menu de atalho chamado quando o Shell exibe um menu de atalho para um membro de um tipo de arquivo. Nesse caso, o manipulador deve ser registrado sob a chave ProgID do tipo de arquivo.

Nomes de manipulador

Para habilitar um manipulador de extensão shell, crie uma subchave com o nome da subchave do manipulador (veja abaixo) na subchave ShellEx do ProgID (para tipos de arquivo) ou o nome do tipo de objeto Shell (para Objetos shell predefinidos).

Por exemplo, se você quisesse registrar um manipulador de extensão de menu de atalho para MyProgram.1, começaria criando a seguinte subchave:

HKEY_CLASSES_ROOT
   MyProgram.1
      ShellEx
         ContextMenuHandlers

Para os manipuladores a seguir, crie uma subchave abaixo da chave "Nome da subchave do manipulador" cujo nome é a versão de cadeia de caracteres do CLSID da extensão shell. Várias extensões podem ser registradas na chave de nome da subchave do manipulador criando várias subchaves.

Para os manipuladores a seguir, o valor padrão da chave "Nome da Subchave do Manipulador" é a versão da cadeia de caracteres do CLSID da extensão shell. Somente uma extensão pode ser registrada para esses manipuladores.

As subchaves especificadas para adicionar Pin ao Menu Iniciar e Fixar na Barra de Tarefas ao menu de atalho de um item só são necessárias para tipos de arquivo que incluem a entrada IsShortCut .

O suporte para manipuladores de provedor de colunas foi removido no Windows Vista. Além disso, a partir do Windows Vista, IPropertySetStorage foi preterido em favor do IPropertyStore.

Embora IExtractImage permaneça com suporte, IThumbnailProvider é preferencial para o Windows Vista e posterior.

Objetos shell predefinidos

O Shell define objetos adicionais em HKEY_CLASSES_ROOT que podem ser estendidos da mesma forma que os tipos de arquivo. Por exemplo, para adicionar um manipulador de folha de propriedades para todos os arquivos, você pode se registrar na chave PropertySheetHandlers .

HKEY_CLASSES_ROOT
   *
      shellex
         PropertySheetHandlers

A tabela a seguir fornece as várias subchaves de HKEY_CLASSES_ROOT sob as quais os manipuladores de extensão podem ser registrados. Observe que muitos manipuladores de extensão não podem ser registrados em todas as subchaves listadas. Para obter mais detalhes, consulte a documentação do manipulador específico.

Observações:

• O menu de atalho em segundo plano da pasta de arquivos é acessado clicando com o botão direito do mouse em uma pasta de arquivo, mas não sobre qualquer conteúdo da pasta.
• "Verbos" são comandos especiais registrados em HKEY_CLASSES_ROOT\Subkey\Shell\Verb .
• ParaTipo\# de Rede\ , "#" é um código de tipo de provedor de rede em decimal. O código de tipo de provedor de rede é a palavra alta de um tipo de rede. A lista de tipos de rede é fornecida no arquivo de cabeçalho Winnetwk.h (valores WNNC_NET_*). Por exemplo, WNNC_NET_SHIVA é 0x00330000, portanto, a chave de tipo correspondente seria HKEY_CLASSES_ROOT\Tipo\ deRede\51 .
• "network_provider_name" é um nome de provedor de rede, conforme especificado por WNetGetProviderName, com os espaços convertidos em sublinhados. Por exemplo, se o provedor de rede da Microsoft Networking estiver instalado, seu nome de provedor será "Microsoft Windows Network" e o network_provider_name correspondente será Microsoft_Windows_Network.

Exemplo de um registro de manipulador de extensão

Para habilitar um manipulador específico, crie uma subchave na chave de tipo do manipulador de extensão com o nome do manipulador. O Shell não usa o nome do manipulador, mas deve ser diferente de todos os outros nomes sob essa subchave de tipo. Defina o valor padrão da subchave de nome para a forma de cadeia de caracteres do GUID do manipulador.

O exemplo a seguir ilustra as entradas do Registro que habilitam manipuladores de extensão de folha de propriedades e menu de atalho, usando um exemplo de tipo de arquivo .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}

O procedimento de registro discutido nesta seção deve ser seguido para todos os sistemas Windows.

Tópicos relacionados

Diretrizes para implementar extensões de In-Process