The userHandle Parameter

When using viInstallHandler() to install handlers for the callback mechanism, your application can use the userHandle parameter to supply a reference to any application-defined value. This reference is passed back to the application as the userHandle parameter to the callback routine during handler invocation. By supplying different values for this parameter, applications can install the same handler with different application-defined contexts.

For example, applications often need information that was received in the callback to be available for the main program. In the past, this has been done through global variables. In VISA, userHandle gives the application more modularity than is possible with global variables. In this case, the application can allocate a data structure to hold information locally. When it installs the callback handler, it can pass the reference to this data structure to the callback handler via the userHandle. This means that the handler can store the information in the local data structure rather than a global data structure.

For another example, consider an application that installs a handler with a fixed value of 0x1 for the userHandle parameter. It can install the same handler with a different value (for example, 0x2) for the same event type on another session. However, installations of the same handler are different from one another. Both handlers are invoked when the event of the given type occurs, but in one invocation the value passed to userHandle is 0x1, and in the other it is 0x2. As a result, you can uniquely identify VISA event handlers by a combination of the handler address and user context pair.

This structure also is important when the application attempts to remove the handler. The operation viUninstallHandler() requires not only the handler's address but also the userHandle value to correctly identify which handler to remove.