EXEMPLO: XLCLIENT: cliente de automatização do Excel

XLCLIENT demonstra como controlar o Microsoft Excel utilizando Automatização OLE. O directório MFC contém um exemplo que utiliza o MFC. O directório SDK contém um exemplo que não utilize o MFC.

O ficheiro seguinte está disponível para transferência a partir do Centro de transferências da Microsoft:
Para obter informações adicionais sobre como transferir ficheiros de suporte da Microsoft, clique no número de artigo que se segue para visualizar o artigo na Microsoft Knowledge Base: Microsoft procedeu de vírus neste ficheiro. Microsoft utilizou o mais recente software de detecção de vírus que estava disponível na data em que o ficheiro foi publicado. O ficheiro é alojado em servidores com segurança avançada que o ajudam a impedir alterações não autorizadas ao ficheiro. Excel expõe a objectos, propriedades e métodos para que um cliente as possa aceder através de automatização OLE. Este exemplo mostra como escrever um cliente de automatização que equivale ao seguinte código do Visual Basic 4.0 que insere valores nas células e cria um gráfico desses valores.

Como escrever um cliente de automatização do Microsoft Excel

Um cliente de automatização utiliza a interface IDispatch para controlar o Microsoft Excel. As seguintes informações são aplicáveis quando escrever um cliente de automatização do Microsoft Excel:

• Consulte a documentação das Microsoft Excel automatização métodos/propriedades que pretende utilizar no ficheiro Vba_xl.hlp que é fornecido com o Excel.
• Os valores das constantes do Microsoft Excel como xlWorkSheet xl3DPie, xlRows etc. pode ser obtido a partir do seguinte artigo da base de dados de conhecimento:
  112671  (http://support.microsoft.com/kb/112671/EN-US/ ) OFF: "incorporadas constantes no Visual Basic for Applications" (WC0993)
  Estes valores constantes também podem ser obtidos a partir biblioteca de tipos do Microsoft Excel utilizando um browser de biblioteca de tipo como Ole2vw32.exe (no directório \bin do compilador). Abra a biblioteca de tipos do Microsoft Excel (por exemplo, Xl5en32.olb para a versão dos e.u.a. do Microsoft Excel 95) utilizando o menu Ficheiro/ViewTypeLibrary de Ole2vw32.exe. Largar combobox typeinfos e seleccione "constantes". As constantes do Microsoft Excel serão apresentadas na caixa de listagem variáveis/DataMembers.
• Todos os argumentos e tipos de retorno de métodos de automatização do Microsoft Excel e tipos são do tipo VARIANT. Os tipos de reais que necessita de ser preenchido para e obtidos de uma VARIANT não são explicitamente indicados na Vba_xl.hlp. No entanto os tipos de ser facilmente adivinhados a partir da documentação. Por exemplo, um número pode ser transferido, VT_I2, uma cadeia como VT_BSTR e um objecto como VT_DISPATCH. O Microsoft Excel irá fazê-coercions adequadas se for necessário. Valores devolvidos pelo Microsoft Excel podem ser adivinhados da mesma forma. Se não for possível determinar o tipo exacto do valor de retorno Verifique o campo VARIANT.vt ou utilizar o tipo de retorno VariantChangeType a utilizar. Conforme mencionado na detalhes"Excel de Microsoft" secção do capítulo 7 no Microsoft Excel Developer Kit no Office Developer Kit no CD da MSDN, o Microsoft Excel nunca irá devolver uma VARIANT com um tipo de dados que está a não ser a seguinte lista:

     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 seguintes informações são aplicáveis para qualquer cliente de automatização:

• OLE utiliza cadeias Unicode. A macro OLESTR pode ser utilizada para converter as constantes string cadeias Unicode. No MFC, variáveis com cadeias podem ser convertidas de e para utilizar as macros T2OLE e OLE2T Unicode. Consulte MFC TechNote 59 para obter detalhes. Código que não utilize MFC pode encontrar informações para a conversão Unicode/ANSI no seguinte artigo da base de dados de conhecimento:
  
  Como converter de ANSI para Unicode & Unicode para ANSI para a OLE ID:138813  (http://support.microsoft.com/kb/138813/EN-US/ )
• O emissor de um método API OLE ou interface é responsável pela libertar argumentos e valores de retorno.

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

1. Suporta AppWizard utilizado para criar uma aplicação com a automatização.
2. Seleccione o separador de automatização OLE no Assistente de classe e seleccione AddClass / de um TypeLibrary OLE. Seleccione a biblioteca de tipos do Excel (Xl5en32.olb dos e.u.a. versão do Microsoft Excel 95) no directório do Microsoft Excel. Seleccione os objectos Microsoft Excel que irá utilizar. ClassWizard irá criar uma classe de proxy COleDispatchDriver derivada para cada objecto que seleccionou. O exemplo seleccionada objectos Application, intervalo, livro, livros, folha de cálculo, gráficos e gráficos do Excel e ClassWizard criadas novas classes no Xl5en32.h e Xl5en32.h. Modificar o nome da falha método para o intervalo de objecto para um nome diferente (por exemplo, caixa de diálogo) porque os ficheiros de cabeçalho do sistema definem falha como DialogBoxA ou DialogBoxW.
3. Inclua o ficheiro cabeçalho gerado no passo 2 para o ficheiro .cpp que irá conter o código para controlar o Microsoft Excel.
4. Argumentos opcionais que são transmitidos não podem ser indicados transferindo uma VARIANT contendo VT_ERROR/DISP_E_PARAMNOTFOUND.
5. Alguns métodos do Microsoft Excel podem ser chamados com dois sintaxes, conforme é documentado Vba_xl.hlp. Por exemplo, o método de livros documentado da seguinte forma:
   Sintaxe 1
   Object.Workbooks(Index)
   
   Sintaxe 2
   Object.Workbooks
   ClassWizard irá gerar apenas um método. Por isso, se necessitar de utilizar a sintaxe, modificar .h gerado e ficheiro .cpp para adicionar outro método para a sintaxe. Por exemplo este exemplo adicionadas Workbooks2 à classe aplicação da seguinte forma para corresponder à sintaxe 2 do método livros:

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

   Workbooks2 tem o mesmo DISPID (0x23c) como livros mas não tem quaisquer argumentos. Este problema não é possível resolver transferindo VT_ERROR/DISP_E_PAMNOTFOUND. Todos os métodos marcado como ter dois sintaxes deve ser processado desta forma.
   
   O exemplo utiliza os métodos de intervalo, livros e gráficos, todos os que têm duas sintaxes. Consequentemente, adiciona Range1 Workbooks2 e Charts2.
6. COleDispatchDriver classe do MFC não suporta argumentos com nome. Os argumentos tem ser transmitidos através da posição.
7. Se o Microsoft Excel gera uma excepção devolverá DISP_E_EXCEPTION de IDispatch::Invoke e preencherá EXCEPINFO parâmetro deste método. MFC irá accionar um COleDispatchException quando isto acontece e o cliente pode obter as informações erro na estrutura de EXCEPINFO por apanhar esta excepção.
8. O código de Doc.cpp no exemplo demonstra como controlar o Microsoft Excel utilizando as classes MFC.

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

1. As funções de programa auxiliar, CreateObject e Invoke Invhelp.cpp e Invhelp.h da amostra de procura no SDK do Win32 podem ser utilizadas para escrever facilmente um cliente de automatização não MFC. Outra abordagem é chamar IDispatch::Invoke directamente. Invocar utiliza-enlace dinâmico para controlar um servidor. Pode ser efectuada mais eficiente modificando-lo para utilizar na qual o DISPID é obtida a partir da biblioteca de tipos em vez de através de IDispatch::GetIDsOfNames de enlace de id.
2. A função de programa auxiliar Invoke não suporta argumentos com nome. Os argumentos tem ser transmitidos através da posição.
3. A função de programa auxiliar Invoke permite uma estrutura EXCEPINFO para ser transmitida como um dos parâmetros. O Microsoft Excel preencherá esta estrutura com informações de erro se que desencadeia uma excepção e se um EXCEPINFO estrutura é fornecida pelo cliente. Invocar irá devolver DISP_E_EXCEPTION quando o Microsoft Excel gera uma excepção. As cadeias in a EXCEPINFO estrutura tem de ser libertada pelo cliente. O código de exemplo não passa uma estrutura EXCEPINFO para o Microsoft Excel.
4. O código de Xlclient.cpp no exemplo demonstra como controlar o Microsoft Excel.