Acessando serviços usando Java

[O Microsoft Agent foi preterido a partir do Windows 7 e pode não estar disponível em versões subsequentes do Windows.]

Você também pode acessar os serviços do Microsoft Agent a partir de um miniaplicativo Java. Muitas das funções acessíveis através das interfaces do Microsoft Agent retornam valores por meio de parâmetros passados por referência. Para passar esses parâmetros do Java, é necessário criar matrizes de elemento único em seu código e passá-las como parâmetros para a função apropriada. Se você estiver usando o Microsoft Visual J++ e tiver executado o Assistente de Biblioteca de Tipos Java no servidor do Microsoft Agent, consulte o arquivo summary.txt para revisar quais funções exigem argumentos de matriz. O procedimento é semelhante ao de C; use a interface IAgentEx para criar uma instância do servidor e, em seguida, carregue o caractere:

private IAgentEx            m_AgentEx = null;
private IAgentCharacterEx   m_Merlin[] = {null};
private int                 m_MerlinID[] = {-1};
private int                 m_RequestID[] = {0};
private final String        m_CharacterPath = "merlin.acs";

public void start()
{
      // Start the Microsoft Agent Server

      m_AgentEx = (IAgentEx) new AgentServer();

      try
      {

         Variant characterPath = new Variant();
         characterPath.putString(m_CharacterPath);

         // Load the character

         m_AgentEx.Load(characterPath,
                    m_MerlinID,
                    m_RequestID);
      }

O procedimento é ligeiramente diferente ao carregar caracteres de um local remoto HTTP, como um site. Nesse caso, o método Load é assíncrono e gerará uma exceção COM de E_PENDING (0x8000000a). Você precisará pegar essa exceção e tratá-la corretamente, como é feito nas seguintes funções:

// Constants used in asynchronous character loads

private final int E_PENDING = 0x8000000a;
private final int NOERROR = 0;


// This function loads a character from the specified path.
// It correctly handles the loading of characters from
// remote sites.

// This sample doesn't care about the request id returned
// from the Load call.  Real production code might use the
// request id and the RequestComplete callback to check for
// a successful character load before proceeding.

public int LoadCharacter(Variant path, int[] id)
{
   int requestid[] = {-1};
   int hRes = 0;

   try
   {
      // Load the character

      m_AgentEx.Load(path, id, requestid);
   }
   catch(com.ms.com.ComException e)
   {
      // Get the HRESULT

      hRes = e.getHResult();
      
      // If the error code is E_PENDING, we return NOERROR

      if (hRes == E_PENDING)
         hRes = NOERROR;
   }

   return hRes;
}

public void start()
{
   if (LoadCharacter(characterPath, m_MerlinID) != NOERROR)
   {
      stop();
      return;
   }

   // Other initialization code here

   .
   .
   .
}

Em seguida, obtenha a interface IAgentCharacterEx que permite aceder aos seus métodos:

// Get the IAgentCharacterEx interface for the loaded
// character by passing its ID to the Agent server.

m_AgentEx.GetCharacterEx(m_MerlinID[0], m_Merlin);

// Show the character

m_Merlin[0].Show(FALSE, m_RequestID);

// And speak hello

m_Merlin[0].Speak("Hello World!", "", m_RequestID);

Da mesma forma, para ser notificado de eventos, você deve implementar o IAgentNotifySink ou o IAgentNotifySinkEx interface, criando e registrando um objeto desse tipo:

...
// Declare an Agent Notify Sink so that we can get
// notification callbacks from the Agent server.

private AgentNotifySinkEx m_SinkEx = null;
private int            m_SinkID[] = {-1};

public void start()
   {
   ...
   // Create and register a notify sink

   m_SinkEx = new AgentNotifySinkEx();

   m_AgentEx.Register(m_SinkEx, m_SinkID);
   …
   // Give our notify sink access to the character

   m_SinkEx.SetCharacter(m_Merlin[0]);
   ...
   }

Para acessar o Microsoft Agent a partir de um miniaplicativo Java, você deve gerar classes Java que você instala com o miniaplicativo. Você pode usar o Visual J++ Java Type Library Wizard, por exemplo, para gerar esses arquivos. Se você planeja hospedar o applet em uma página da Web, precisará construir um Java CAB assinado incluindo os arquivos de classe gerados que são baixados com a página. Os arquivos de classe são necessários para acessar o Microsoft Agent Server, uma vez que é um objeto COM, que é executado fora da área restrita Java.