EXEMPLO: XLCLIENT: cliente de automação para o Excel

XLCLIENT demonstra como controlar o Microsoft Excel usando automação OLE. O diretório MFC contém um exemplo que usa o MFC. O diretório SDK contém um exemplo que não use MFC.

O seguinte arquivo está disponível para download no Centro de download da Microsoft:
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. Excel expõe seus objetos, propriedades e métodos para que um cliente pode acessá-los através de automação OLE. Este exemplo mostra como escrever um cliente de automação que é equivalente ao seguinte código Visual Basic 4.0 que insere valores de células e cria um gráfico desses valores.

Como escrever um cliente de automação para o Microsoft Excel

Um cliente de automação usa a interface IDispatch para o controle Microsoft Excel. As informações seguintes são aplicáveis ao escrever um cliente de automação para o Microsoft Excel:

• Leia a documentação das Microsoft Excel automação métodos/propriedades que você pretende usar no arquivo Vba_xl.hlp que é fornecido com o Excel.
• Os valores de constantes do Microsoft Excel como xlWorkSheet xl3DPie, xlRows etc. podem ser obtidas com o seguinte artigo da base de dados de Conhecimento:
  112671  (http://support.microsoft.com/kb/112671/EN-US/ ) OFF: "internos constantes no Visual Basic for Applications" (WC0993)
  Esses valores constantes também podem ser obtidas de biblioteca de tipos do Microsoft Excel usando um navegador da biblioteca de tipo como Ole2vw32.exe (no diretório \bin do compilador). Abrir biblioteca de tipos do Microsoft Excel (por exemplo, Xl5en32.olb para a versão dos EUA do Microsoft Excel 95) usando o menu Arquivo/ViewTypeLibrary de Ole2vw32.exe. Cancele a caixa de combinação typeinfos e selecione "constantes". As constantes do Microsoft Excel serão exibidas na caixa de lista de variáveis/DataMembers.
• Todos os argumentos e tipos de retorno de métodos de automação do Microsoft Excel e tipos são do tipo VARIANT. Os tipos de reais que precisam ser preenchidos em e recuperados de um VARIANT não são explicitamente indicados em Vba_xl.hlp. No entanto os tipos podem ser facilmente adivinhados da documentação. Por exemplo, um número pode ser passado como VT_I2, uma seqüência de caracteres como VT_BSTR e um objeto como VT_DISPATCH. Microsoft Excel fará coercions apropriadas se necessário. Valores retornados pelo Microsoft Excel podem ser adivinhadas da mesma forma. Se o tipo exato do valor de retorno não pode ser determinado Verifique o campo VARIANT.vt ou forçar o tipo de retorno usando VariantChangeType. Conforme mencionado na "Microsoft Excel especificações" seção do capítulo 7 no Kit do desenvolvedor do Microsoft Excel no Kit do desenvolvedor do Office no CD do MSDN, o Microsoft Excel nunca retornará uma VARIANT com um tipo de dados que está não na lista a seguir:

     Data Type                               Variant Constant
     ---------                               ----------------
     Boolean                                 VT_BOOL
     Currency (scaled integer)               VT_CY
     Date                                    VT_DATE
     Error cell values (#N/A, #REF etc.)     VT_ERROR
     Integer                                 VT_I2
     Long (long integer)                     VT_I4
     Object                                  VT_DISPATCH
     Single (single-precision floating-point)VT_R4
     Double (double-precision floating-point)VT_R8
     String                                  VT_BSTR
  						

As informações seguintes são aplicáveis a qualquer cliente de automação:

• OLE usa seqüências de caracteres Unicode. A macro OLESTR pode ser usada para converter constantes de seqüência de caracteres em cadeias de caracteres Unicode. No MFC, variáveis que contêm seqüências de caracteres podem ser convertidas e para Unicode usando as macros T2OLE e OLE2T. Consulte MFC TechNote 59 para obter detalhes. Código que não use MFC pode encontrar informações para conversão Unicode/ANSI no seguinte artigo da base de dados de Conhecimento:
  
  A conversão de ANSI para Unicode e Unicode para ANSI para OLE identificação:138813  (http://support.microsoft.com/kb/138813/EN-US/ )
• O chamador de um método API OLE ou interface é responsável pela liberação argumentos e valores de retorno.

Como escrever um cliente de automação do MFC para o Microsoft Excel

1. Oferece suporte a AppWizard usado para criar um aplicativo com automação.
2. Selecione a guia automação OLE no Assistente de classe e selecione AddClass / de um OLE TypeLibrary. Selecione a biblioteca de tipos do Excel (Xl5en32.olb do governo versão do Microsoft Excel 95) no diretório do Microsoft Excel. Selecione os objetos Microsoft Excel que você usará. ClassWizard criará uma classe de proxy COleDispatchDriver derivada para cada objeto que você selecionar. O exemplo selecionado objetos Application, Range, pasta de trabalho, pastas de trabalho, planilha, gráfico e gráficos Excel e ClassWizard criadas novas classes no Xl5en32.h e Xl5en32.h. Modifique o nome da DialogBox método do intervalo do objeto com um nome diferente (por exemplo, caixa de diálogo) porque os arquivos de cabeçalho do sistema definem DialogBox como DialogBoxA ou DialogBoxW.
3. Inclua o arquivo cabeçalho gerado na etapa 2 para o arquivo .cpp que conterá o código para o controle Microsoft Excel.
4. Argumentos opcionais que são passados não podem ser indicados passando um VARIANT contendo VT_ERROR/DISP_E_PARAMNOTFOUND.
5. Alguns métodos do Microsoft Excel podem ser chamados usando duas sintaxes, conforme documentado no Vba_xl.hlp. Por exemplo, o método de pastas de trabalho é documentado da seguinte maneira:
   Sintaxe 1
   Object.Workbooks(index)
   
   Sintaxe 2
   Object.Workbooks
   ClassWizard irá gerar apenas um método. Portanto, se você precisar usar outro sintaxe, modificar .h gerado e arquivo .cpp para adicionar outro método para a outra sintaxe. Por exemplo neste exemplo adicionado Workbooks2 à classe aplicativo da seguinte maneira para corresponder à sintaxe 2 do método WorkBooks:

      VARIANT Application::Workbooks2()
      {
      VARIANT result;
      InvokeHelper(0x23c, DISPATCH_METHOD, VT_VARIANT, (void*)&result, NULL);
      return result;
      }
   						

   Workbooks2 tem o mesmo DISPID (0x23c) como pastas de trabalho mas não tem argumentos. Esse problema não pode ser resolvido passando VT_ERROR/DISP_E_PAMNOTFOUND. Todos os métodos marcado como ter duas sintaxes deve ser manipulado dessa maneira.
   
   O exemplo usa os métodos de intervalo, pastas de trabalho e gráficos, todos os que têm duas sintaxes. Conseqüentemente, ele adiciona Range1, Workbooks2 e Charts2.
6. Classe de COleDispatchDriver do MFC não oferece suporte para argumentos nomeados. Argumentos devem ser passados por posição.
7. Se o Microsoft Excel gera uma exceção, ele retornará DISP_E_EXCEPTION IDispatch:: Invoke e preencherá EXCEPINFO parâmetro desse método. MFC lançará uma COleDispatchException quando isso acontece e o cliente pode obter as informações de erro na estrutura de EXCEPINFO por captura essa exceção.
8. O código na Doc.cpp no exemplo demonstra como controlar o Microsoft Excel usando as classes do MFC.

Como escrever um cliente de automação não MFC para o Microsoft Excel

1. As funções do auxiliar, CreateObject e Invoke em Invhelp.cpp e Invhelp.h da amostra BROWSE no SDK do Win32 podem ser usadas para escrever facilmente um cliente de automação não MFC. Outra abordagem é chamar IDispatch:: Invoke diretamente. Chama usa ligação atrasada para controlar um servidor. Ele pode ser feito mais eficiente, modificando-usar ligação de identificação no qual o DISPID é obtido da biblioteca de tipo, em vez de IDispatch::GetIDsOfNames.
2. A função de auxiliar Invoke não oferece suporte a argumentos nomeados. Argumentos devem ser passados por posição.
3. A função de auxiliar Invoke permite uma estrutura EXCEPINFO a ser passado como um dos parâmetros. Microsoft Excel preencherá essa estrutura com informações de erro se ele gera uma exceção e se um EXCEPINFO estrutura é fornecida pelo cliente. Chamar irá retornar DISP_E_EXCEPTION quando o Microsoft Excel gera uma exceção. As seqüências de caracteres a EXCEPINFO estrutura deve ser liberada pelo cliente. O código de exemplo não passa uma estrutura EXCEPINFO para o Microsoft Excel.
4. O código na Xlclient.cpp no exemplo demonstra como controlar o Microsoft Excel.