Creating an agent client

Creating an agent client

In the following explanation, C++ notation is used, but the same behaviour can be assumed for CLIPS programs.

To create a client, you need to derive from two classes, agClient and agConnection.

Derive from agClient in order to override the OnMakeConnection function, and create an instance of this class.
Derive from agConnection in order to override various On... functions. An instance of this class will be created by OnMakeConnection when a client attempts to connect to your server.

When you have created an instance of your client object, you call MakeConnection to create a connection. If successful, a connection object is returned. If not successful (for example, the server is not running), NULL is returned.

When a client agent wishes the server to execute a KQML command, it will call KQMLExecute on its end of the connection. At the server side, OnKQMLExecute is called, and the server agent should interpret the KQML appropriately. The client should explicitly issue a KQMLRequest to retrieve results of a KQMLExecute message. The client receives a KQMLAdvise message when the server has finished performing the requested task.

The server's connection object(s) will be deleted automatically when the client breaks the connection with Disconnect. The connection can be held for the duration of several messages, or the client can opt to keep making and breaking connections with each message.

The following is an example fragment of a simple client agent.

  class MyConnection: public agConnection
  {
   public:
    MyConnection(wxIPCObject *clientOrServer):agConnection(clientOrServer)
    {}
    ~MyConnection(void) {}
    Bool OnKQMLAdvise(expression *expr);
  };

  class MyClient: public agClient
  {
   public:
    MyClient(void) {}
    wxConnection *OnMakeConnection(void)
    { return new MyConnection(this); }
  };

  Bool MyConnection::OnKQMLAdvise(expression *kqml)
  {
    // Do something with the kqml expression  here
    ...
    return TRUE;
  }

  // MAIN PROGRAM

  // Create a new client
  MyClient *my_client = new MyClient;
  
  // Connect to the server
  MyConnection *the_connection = (MyConnection *)my_client->MakeConnection("", "MyServerName", "");
  if (!the_connection)
    return;

  // Ask for it to calculate a factorial
  the_connection->KQMLExecuteString("(ask :task-id 100 :content (calc-factorial 10))");
  
  // Get the result
  expression *result = the_connection->KQMLRequest(100);
  if (result)
  {
    // Get the status and value
    char *status = KQMLGetKeywordValueString("status", result);
    if (strcmp(status, "completed") == 0)
    {
      char *value = KQMLGetKeywordValueString("content", result);
      wxString str("The factorial of 10 is ");
      str += value;
      wxMessageBox(value, "Result", wxOK);
      
    }
  }
  the_connection->Disconnect();