Accesso ai servizi tramite Java

[Microsoft Agent è deprecato a partire da Windows 7 e potrebbe non essere disponibile nelle versioni successive di Windows.]

È anche possibile accedere ai servizi di Microsoft Agent da un applet Java. Molte delle funzioni accessibili tramite le interfacce di Microsoft Agent restituiscono valori tramite parametri passati per riferimento. Per passare questi parametri da Java, è necessario creare matrici a singolo elemento nel codice e passarle come parametri alla funzione appropriata. Se si usa Microsoft Visual J++ ed è stata eseguita la Creazione guidata libreria dei tipi Java nel server Microsoft Agent, fare riferimento al file summary.txt per esaminare quali funzioni richiedono argomenti di matrice. La procedura è simile a quella in C; usare l'interfaccia IAgentEx per creare un'istanza del server, quindi caricare il carattere:

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);
      }

La procedura è leggermente diversa quando si caricano caratteri da una posizione remota HTTP, ad esempio un sito Web. In questo caso il metodo Load è asincrono e genererà un'eccezione COM di E_PENDING (0x8000000a). Sarà necessario intercettare questa eccezione e gestirla correttamente come avviee nelle funzioni seguenti:

// 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

   .
   .
   .
}

Ottenere quindi l'interfaccia IAgentCharacterEx che consente di accedere ai relativi metodi:

// 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);

Analogamente, per ricevere una notifica degli eventi, è necessario implementare l'interfaccia IAgentNotifySink o IAgentNotifySinkEx , creando e registrando un oggetto di quel 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]);
   ...
   }

Per accedere a Microsoft Agent da un applet Java, è necessario generare classi Java installate con l'applet. È possibile usare la Creazione guidata libreria dei tipi Java di Visual J++, ad esempio, per generare questi file. Se si prevede di ospitare l'applet in una pagina Web, sarà necessario compilare un file CAB Java firmato che include i file di classe generati scaricati con la pagina. I file di classe sono necessari per accedere a Microsoft Agent Server perché si tratta di un oggetto COM, che viene eseguito all'esterno della sandbox Java.