SDK Asynchronous Operation

By default, all API methods that generate responses from the Active Worlds servers will block until the response is received. For some SDK applications, such as interactive programs that need to respond to events from a user interface, this blocking behavior may be undesirable. In this case the application can switch a particular method or methods into asynchronous mode by installing a callback for that particular method. If a method has a callback installed, that method will return immediately without waiting for a reply from the server. The callback function will be called later by the SDK when the server's response is received.

Callback functions are similar to event handlers, however they have one argument, a return code. The return code is a numeric value indicating whether the operation succeeded or not. A value of RC_SUCCESS (0, zero) indicates successful completion.

All callbacks have the same prototype:

   void callback (int rc);

Example of a callback implementation:

   void callback (int rc)
   {
     if (rc)
       printf ("Operation failed (reason %d)\n", rc);
     else
       puts ("Operation succeeded\n");
   }

Applications install callbacks by calling aw_callback_set for the methods they wish to complete asynchronously. Note that since not all methods can block, not all methods have callbacks. Methods that have callbacks are so noted with a Callback section on the page describing that method.