EXEMPLO: Comaddin.exe Office 2000 suplemento escrito em Visual C++

Comaddin.exe é um executável de extração automática que demonstra a criação de um Office 2000 ou Office XP COM (Component Object Model) suplemento usando o Visual C++. Um suplemento é um servidor de COM em processo projetado especificamente para ser executado dentro do contexto de aplicativos de um ou mais Office 2000 ou Office XP. Suplementos fornecem um método flexível, eficiente e uniforme de estender o ambiente do Office.

Suplementos de COM são criados usando qualquer linguagem de programação que pode criar componentes COM, tais como Visual Basic, C/C ++, translation from VPE for Csharp e o Office 2000 Developer ou Office XP Developer edition do Visual Basic for Applications (VBA).

Este exemplo demonstra as etapas necessárias para criar um suplemento de COM no Visual C++. O exemplo cria um shell de suplemento básico que você pode estender para criar seu próprio suplemento do Office.

O seguinte arquivo está disponível para download no Centro de download da Microsoft:
Data de lançamento: 4 de janeiro de 1999

Para obter informações adicionais sobre como baixar arquivos de suporte da Microsoft, clique no número abaixo para ler o artigo na Base de dados de Conhecimento da Microsoft: Microsoft examinou esse arquivo em busca de vírus. Microsoft utilizou o mais recente software de detecção de vírus que estava disponível na data em que o arquivo foi publicado. O arquivo é armazenado em servidores com segurança avançada que ajudam a evitar qualquer alteração não autorizada no arquivo.

Informações do arquivo de exemplo

Comaddin.exe extrai os seguintes arquivos para uma pasta de sua escolha:

IDTExensibility2

Para um objeto COM um Office adicionar-no, ele deve oferecer suporte a interface IDTExensibility2 conforme descrito na biblioteca do Microsoft Add-In Designer tipo (Msaddndr.dll). Esta interface foi declarada para você no ComAddin.h importação não é necessária. Todos os suplementos herdam de nesta interface e devem implementar cada um dos seus cinco métodos:

• OnConnection
• OnDisconnection
• OnAddInsUpdate
• OnStartupComplete
• OnBeginShutdown

Quando um suplemento é carregado pela primeira vez, é feita uma chamada QueryInterface para IDTExtensibility2. Se essa chamada falhar, o suplemento é descarregado. Se a chamada tiver êxito, o aplicativo host usará a referência retornada para notificar o add-in das alterações feitas ao seu estado. Segue uma descrição de cada método.

OnConnection

O evento OnConnection é acionado sempre que o suplemento está conectado. O add-in o pode estar conectado na inicialização, pelo usuário final, ou através de automação. Se OnConnection Retorna S_OK, o add-in é considerado ser carregado. Se qualquer outro valor for retornado, o aplicativo host irá liberar imediatamente sua referência para o suplemento e o objeto será destruído.

OnConnection usa os seguintes quatro parâmetros:

• Aplicativo - uma referência para a interface IDispatch do aplicativo host.
• ConnectMode - uma constante que especifica como o suplemento foi conectado.
  • ext_cm_AfterStartup - iniciado pelo usuário final na caixa de diálogo COM add-ins.
  • ext_cm_CommandLine - conectado a partir da linha de comando.
  • ext_cm_External - conectado por um aplicativo externo através da automação.
  • ext_cm_Startup - iniciado por host na inicialização do aplicativo. Esse comportamento pode ser controlado por uma configuração no registro.
• AddInInst - uma referência ao objeto COMAddIn que se refere a este suplemento na coleção COMAddIns para o aplicativo host.
• Personalizado - uma matriz de tipos Variant pode armazenar dados definidos pelo usuário.

OnDisconnection

O evento OnDisconnection é acionado quando o suplemento está desconectado e apenas antes que ele descarrega da memória. O add-in deve executar qualquer limpeza de recursos nesse evento e restaurar as alterações feitas ao aplicativo host.

OnDisconnection usa dois parâmetros a seguintes:

• RemoveMode - uma constante que especifica como o suplemento foi desconectado.
  • ext_dm_HostShutdown - desconectado quando o aplicativo host fechado.
  • ext_dm_UserClosed - desconectada pelo usuário final ou um controlador de automação.
• Personalizado - uma matriz de tipos Variant pode armazenar dados definidos pelo usuário.

OnAddInsUpdate

O evento OnAddInsUpdate é acionado quando altera o conjunto de suplementos de COM registrados. Em outras palavras, sempre que um suplemento está instalado ou removido o aplicativo host, este evento é acionado.

OnStartupComplete e OnBeginShutdown

Ambos os OnStartupComplete OnBeginShutdown eventos e notificam o suplemento quando o aplicativo host deixou ou está entrando em um estado onde interação do usuário deve ser evitada porque o aplicativo está ocupado carregando ou descarregando próprio da memória. OnStartupComplete será disparado somente se o suplemento foi conectado durante a inicialização e OnBeginShutdown será disparado somente se o add-in for desconectado pelo host durante o desligamento.

Como a interface de usuário para o aplicativo host é totalmente ativa quando esses eventos acionados, eles podem ser a única maneira executar determinadas ações caso contrário, seria não está disponíveis de OnConnection e OnDisconnection.

Registrar o suplemento de com

Em além para registro COM normal, um suplemento precisa se registrar com cada aplicativo do Office 2000 no qual ele pode executar com segurança. Para se registrar com um determinado aplicativo, o add-in cria uma subchave, usando o ProgID como o nome para a chave, no seguinte local:

O add-in pode fornecer valores neste local chave para um nome para exibição amigável e uma descrição completa. Além disso, o suplemento deve especificar seu comportamento de carga desejada usando um valor DWORD chamado "LoadBehavior." Esse valor determina como o suplemento será carregado pelo aplicativo host e é composto de uma combinação dos seguintes valores:

• 0 x 00 = desconectar - Não É carregado.
• 0 x 01 = conectado - É carregado.
• 0 x 02 = bootload - carregar na inicialização do aplicativo.
• 0 x 08 = demandLoad - carga somente quando solicitado pelo usuário.
• 0 x 16 = ConnectFirstTime - carregar apenas uma vez (na próxima inicialização).

O valor típico especificado é 0 x 03 (conectado | Bootload).

Suplementos que implementam IDTExtensibility2 também devem especificar um DWORD valor chamado "CommandLineSafe" para indicar se eles são seguros para operações que não oferecem suporte a uma interface de usuário. Um valor de 0 x 00 significa False, 0 x 01 é True. Porque este exemplo exibe uma caixa de mensagem, ele não é seguro para execução de linha de comando e, portanto, define o valor para 0 x 00.

Guia de Introdução

Para começar a escrever suplementos, compilar o projeto de exemplo, executar regsvr32.exe na DLL interna e, em seguida, iniciar o Microsoft Word, Excel, PowerPoint e/ou FrontPage 2000. Você deve ver uma caixa de diálogo Abrir como o add-in é carregado que diz "Hello" e informa que aplicativo está em.

(c) 1999 Microsoft Corporation, todos os direitos reservados. Contribuições de Richard r. José, Microsoft Corporation.