Criando manipuladores de extensão de shell

Os recursos do Shell podem ser estendidos com entradas de registro e arquivos .ini. Embora essa abordagem para estender o Shell seja simples e adequada para muitos propósitos, 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 diferentes arquivos do mesmo tipo. Outros aspetos do Shell, como a folha de propriedades de que pode ser exibida quando um ficheiro é clicado com o botão direito, não podem ser modificados com o registo.

Uma abordagem mais poderosa e flexível para estender o Shell é implementar manipuladores de extensão do 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-lhe 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 toda vez que um dos arquivos for clicado com o botão direito do mouse. O manipulador pode especificar itens de menu adicionais 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 estão associados a um tipo de arquivo específico e permitem que você especifique arquivo por 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 que são comuns a todos os manipuladores de extensão do Shell.

• Implementando manipuladores de extensão de shell
  • Implementando IPersistFile
  • Implementando IShellExtInit
  • Personalização da Infotip
• Aprimorando o Windows Search com manipuladores de extensão do Shell
• Registar Manipuladores de Extensão de Shell
  • Nomes do manejador
  • Objetos de Shell Predefinidos
  • Exemplo de um registo de manipulador de extensão
• Tópicos relacionados

Implementação de Manipuladores de Extensões do Shell

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

Muitos manipuladores de extensão do Shell são objetos COM (Component Object Model) em processo. Eles devem receber um GUID e ser registrados conforme descrito em Registrando manipuladores de extensão do shell. Eles são implementados 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. COM chama essa função para determinar se o objeto está servindo a algum cliente. Se não, o sistema pode descarregar a DLL e liberar a memória associada.

Como todos os objetos COM, os manipuladores de extensão Shell devem implementar uma interface IUnknown e uma fábrica de classe . 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 IInitializeWithStreamIInitializeWithItem e IInitializeWithFile no Windows Vista. O Shell usa essas interfaces para inicializar o manipulador.

A interface IPersistFile deve ser implementada da seguinte forma:

• Manipuladores de dados
• Manipuladores de gotas

No passado, os manipuladores de ícones também eram obrigados a implementar IPersistFile, mas isso não é mais verdade. Para manipuladores de ícones, IPersistFile agora é opcional e outras interfaces como IInitializeWithItem são preferidas.

A interfaceIShellExtInit deve ser implementada da seguinte forma:

• Manipuladores de menu de atalho
• Controladores de arrastar e largar
• Manipuladores de ficha de propriedades

Implementando IPersistFile

O 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 próprios, e o método GetClassID, que herda de IPersist. Com extensões Shell, IPersist é usado apenas para inicializar um objeto 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ão token.

O Shell chama GetClassID primeiro e a função retorna o identificador de classe (CLSID) 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 é necessário aceder aos ficheiros, 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 típico do Shell implementa os métodos GetClassID e Load. Ele é 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 mantém o ponteiro de uma pasta para uma lista de identificadores de item (PIDL). 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 de arrastar e soltar não padrão, é 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 em CF_HDROP formato.
• hRegKey contém uma chave do Registro para o objeto de arquivo ou tipo de pasta.

O método IShellExtInit::Initialize armazena o nome do ficheiro, ponteiro IDataObject e a chave do registo 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 contém 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_szFileNamee m_hRegKey são variáveis privadas usadas para armazenar as informações que são 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, a função DragQueryFile é usada 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 atribui o identificador a m_hRegKey.

Personalização da dica de informação

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

• Implemente um objeto que suporte IQueryInfo e, em seguida, 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 no {CLSID} chave da sua extensão de namespace. Defina o valor dessa entrada como a cadeia de caracteres literal que você deseja exibir, como 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 no ProgID chave 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 propriedades canônicas, pares de identificador de formato (FMTID)/identificador de propriedade (PID) 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ônico (como System.Date) e {fmtid},pid é um parFMTID/PID.

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

Os seguintes nomes de propriedade podem ser usados:

Aprimorando o Windows Search 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 se integrar 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 do shell

Um objeto 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 Shell.

Sempre que você criar ou alterar um manipulador de extensão 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 pode não ser reconhecida até que o sistema seja reinicializado.

Como em 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, deve-se 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 rosca Apartamento.

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, portanto, controla 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 registado sob a chave de ProgID do tipo de arquivo.

Nomes dos manipuladores

Para habilitar um manipulador de extensão Shell, crie uma subchave com o nome da subchave do manipulador (veja abaixo) sob a subchave ShellEx do ProgID (para tipos de arquivo) ou o nome do tipo de objeto Shell (para Predefined Shell Objects).

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

HKEY_CLASSES_ROOT
   MyProgram.1
      ShellEx
         ContextMenuHandlers

Para os manipuladores a seguir, crie uma subchave abaixo da chave "Handler Subkey name" cujo nome é a versão de cadeia de caracteres do CLSID da extensão Shell. Várias extensões podem ser registradas sob a 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. Apenas uma extensão pode ser registrada para esses manipuladores.

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

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

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

Objetos de 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 painel de propriedades para todos os ficheiros, pode registar-se sob a 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 de plano de fundo 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 sob HKEY_CLASSES_ROOT\Subchave\Shell\Verb .
• Para Tipo\de Rede\#, "#" é um código de tipo de provedor de rede como número decimal. O código de tipo de provedor de rede é a palavra alta de um tipo de rede. A lista de tipos de rede é dada 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\Network\Type\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 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 registo de manipulador de extensão

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

O exemplo a seguir ilustra entradas do Registro que habilitam manipuladores de extensão de menu de atalho e folha de propriedades, usando um tipo de arquivo .myp de exemplo:

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

Orientações para a implementação de extensões In-Process