Using the Callback Model

All callback functions that you register must use the following function prototype:

BrokerBoolean <your_function_name_goes_here>(  
  BrokerClient client,  
  BrokerEvent event,  
  void *client_data);

Your function should return 1 (true) if its processing was successful or 0 (false) if a failure occurred. If 1 (true) is returned, the event will be acknowledged automatically. For information on acknowledging events, see Using Sequence Numbers.

When you register your callback function, you may specify a client_data pointer to any user-defined data that may be necessary for the function to complete its processing. The client_data parameter might be used to point to state information that the callback function must access and update each time it is invoked.

Assume that you want to count the number of events that your application processes. When you register your callback function, you could use the client_data pointer to point to the counter variable. When the callback is invoked, it can increment the counter.

The following example illustrates how to set up an argument for a callback function.

BrokerBoolean sample_callback(BrokerClient c, BrokerEvent e, void *counter);  
long count = 0;  
. . .  
int main(int argc, char **argv)  
{  
  BrokerClient c;  
  long n;  
  . . .  
  /* Check if can subscribe */  
  . . .  
  /* Register callback */  
  err = awRegisterCallbackForSubId(c, 1, sample_callback, &n);  
  if (err != AW_NO_ERROR) {  
  printf("Error on registering callback\n%s\n", awErrorToString(err));  
  return 0;  
  }  
. . .

The following example illustrates how to use the client data parameter in a callback function:

BrokerBoolean sample_callback(BrokerClient c, BrokerEvent e,  
        void *counter)  
{  
  /* increment counter */  
  (*(long*)counter)++;  
  /* perform rest of event processing */  
  . . .  
}

The example below illustrates the use of the awRegisterCallback function to register a general callback function.

The following example illustrates how to process events with a general callback function.

. . .  
BrokerBoolean sample_callback(BrokerClient c, BrokerEvent e, void *data);  
. . .  
/* Create a client */  
. . .  
/* Check if can subscribe */  
. . .  
/* Register a general callback */  
err = awRegisterCallback(c, sample_callback, NULL);  
if (err != AW_NO_ERROR) {  
  printf("Error on registering callback\n%s\n", awErrorToString(err));  
  return 0;  
}  
/* Open the subscription */  
err = awNewSubscription(c,"Sample::SimpleEvent",NULL);  
. . .  
/* Do the main loop */  
err = awMainLoop();  
if (err != AW_NO_ERROR) {  
  printf("Error in main loop\n%s\n",awErrorToString(err));  
  return 0;  
}  
. . .

The example below illustrates the use of the awRegisterCallbackForSubId function to register a specific callback function.

. . .  
BrokerBoolean general_callback(BrokerClient c, BrokerEvent e,  
        void *data);  
BrokerBoolean specific_callback(BrokerClient c, BrokerEvent e,  
        void *data);  
/* Check if can subscribe */  
. . .  
/* Register a general callback */  
err = awRegisterCallback(c, general_callback, NULL);  
if (err != AW_NO_ERROR) {  
  printf("Error on registering callback\n%s\n", awErrorToString(err));  
  return 0;  
}  
/* Register a specific callback */  
err = awRegisterCallbackForSubId(c, 1, specific_callback, NULL);  
if (err != AW_NO_ERROR) {  
  printf("Error on registering callback\n%s\n", awErrorToString(err));  
  return 0;  
}  
/* Open the subscription with the ID of 1 */  
err = awNewSubscriptionWithId(c, 1, "Sample::SimpleEvent",NULL);  
. . .  
/* Do the main loop */  
err = awMainLoop();  
if (err != AW_NO_ERROR) {  
  printf("Error in main loop\n%s\n",awErrorToString(err));  
  return 0;  
}  
. . .

The awDispatch function may be used to wait to receive a single event for any Broker client, dispatch the event to the appropriate callback function, and then return. The subscribe2.c and subscribe4.c sample applications provide examples of how to use awDispatch.

The awMainLoop function is similar to awDispatch, except that it enters an event loop that will continue to receive and dispatch events until awStopMainLoop is called. The subscribe3.c sample application provides an example of how to use awMainLoop.

In a multi-threaded environment, the awThreadedCallbacks function will spawn a thread that then invokes awMainLoop. This function simplifies your client application code by handling the thread creation for you.

Invoking awThreadedCallbacks(1) is identical to creating a thread and then invoking the awMainLoop method on that thread.

Invoking awThreadedCallbacks(0) is identical to invoking the awStopMainLoop method.

When an event is received in the callback model, the following rules are used to dispatch the event.

1. If the received event has a tag field and the tag matches a registered callback, the received event is dispatched to that callback function.
2. If the received event has a subscription identifier, the event is dispatched once to each callback that matches the subscription identifier. If the event matches two event subscriptions with the same subscription identifier, the event will be dispatched twice to the callback function for that identifier.
3. The received event will be dispatched to the general callback function if the tag did not match any callback and:
   1. At least one subscription identifier did not match a specific callback.
   2. No subscription identifiers were matched because the event was delivered.