Introduction to Callbacks

TIBCO SmartSockets makes heavy use of callbacks let you see into its internal processing. A callback is an object-oriented mechanism that allows you to be notified when a specified event occurs, such as a message is placed into the input queue. The callback can be associated with a certain event or with all events of a certain type (called global callbacks). When the event occurs, the specified callback function is called to notify you that the event happened.

A very brief introduction to callbacks is provided in this tutorial. See the TIBCO SmartSockets Application Programming Interface reference for a more detailed discussion of callbacks.

They do not return a value (the functions are of type void). Callback functions can be used to affect the processing of a program, or to simply receive notification of some event.

They have a priority associated with them that allows the order to be specified. The priority specifies the order in which callbacks are called. Higher priority callbacks are called before lower priority ones. If two callbacks have the same priority, their relative calling order is undetermined.

They are uniquely identified by function and argument within a given list. This means that two callbacks cannot be registered that use the same callback function and callback argument within the same list of callbacks.

They all take exactly three arguments. The first is the object to which the callback is related, such as the RTserver connection, the second points to a type-specific callback data structure, such as a message, and the third is a user-specified argument that is specified when the callback is created. Depending on the callback type, the first argument may not be used.

Creating Callbacks

A callback function is created using the function TipcSrvTypeCbCreate where Type is replaced with one of the types listed in Callback Types. For example, to create an error callback function, such as my_srv_error_cb, that is invoked when a non-recoverable error occurs on your program’s connection to RTserver, add this code:

cb = TipcSrvErrorCbCreate(my_srv_error_cb, NULL); 
if (cb == NULL) { 
  /* error */ 
}

In general, you should always check to make sure the callback was successfully created. You also need to write the code for the callback function my_srv_error_cb.

Manipulating Callbacks

A callback function is looked up using the function TipcSrvTypeCbLookup, where Type is replaced with one of the types listed in the section Callback Types.

Callback functions are manipulated using these TIBCO SmartSockets TutCb* utility functions:

TutCbGetArgument — return the callback argument of the specified callback

TutCbGetFunction — return the callback function of the specified callback

TutCbGetPriority — return the current priority of a callback

TutCbSetArgument — set the callback argument used by the specified callback

TutCbSetFunction — set the callback function to be called

TutCbSetPriority — set the priority of a callback

See the TIBCO SmartSockets Utilities reference for more details on these functions.

Destroying Callbacks

Callbacks should be destroyed when they are no longer needed to free memory and ensure they are not invoked accidentally. In TIBCO SmartSockets, callbacks are destroyed using the TutCbDestroy function.

Callback Types

Within TIBCO SmartSockets there are a number of different callback types associated with a connection. In this lesson, you work with callbacks that are associated with a program’s connection to RTserver. Callbacks are conceptually equivalent to dynamically adding a line of code to a program. This table gives a brief summary of the different callback types available within TIBCO SmartSockets.


Callback Type	Description
Decode	Executed after an incoming message is read from a connection’s socket
Default Process	Executed if no process callback exists for the given type
Default Subject	Executed if no subject callbacks exists for the given destination
Encode	Executed after an outgoing message is turned into a packet for transmission over the connection’s socket
Error	Executed when an unrecoverable error occurs
Process	Executed while processing a message of a given type
Queue	Executed when a message is inserted into or deleted from a program’s message queue
Read	Executed when an incoming message is read from RTserver into the read buffer of the program and first unpacked into a message
Server Create	Executed when an RTclient connects to RTserver
Server Destroy	Executed when an RTclient disconnects from RTserver
Subject	Executed while processing a message with the given destination, such as subject
Write	Executed when an outgoing message is sent to RTserver

These callbacks that TIBCO SmartSockets offers allow you to customize your code and usage of TIBCO SmartSockets to almost any level. For example, if you are interested in adding your own security, you may use the Encode, Decode, Server Create, and Server Destroy callbacks.

Although there are many types of callbacks available in TIBCO SmartSockets, you only need to understand Process or Subject callbacks to begin processing messages in an event-driven manner. In this Lesson, you will see some example programs which illustrate the use of the common types of callbacks.