MPIControlEventCallback

Definition

typedef void (MPI_DECL2 *MPIControlEventCallback)
	(MPIControl control, 
          const MPIEventData *eventData, 
          void *userData);

 

Required Header: stdmpi.h

Change History: Added in 04.00.

Description

MPIControlEventCallback is the type definition for controller event callback functions.

Functions with an identical signature can be used as callback functions to handle controller-based events.  These events include normal motion completion, motor limits, fault conditions, network node faults, and many other events as well.

WARNING! Exceptions that occur in the callback function must not propagate back into the MPI library.  This causes the parent thread to exit and may cause the application to crash.  This typically applie­s to C++ exceptions, which can occur on any operating system, but also to Microsoft’s structured exceptions which is found on Windows® operating systems.

control The MPIControl object handle associated with the controller that generated the event.
*eventData A pointer to the MPIEventData structure holding the information associated with the event.
*userData A user-specified piece of data associated with the callback function when added to the callback list by mpiControlEventCallbackAdd(…). This piece of information can be the address of a C++ object in order to make the callback act as a callback functor (an object-based callback method).

Return Values

The callback function may pass back error codes that are passed back to mpiControlProcessEvents.  Returning something other than MPIMessageOK does not stop the processing of other callback functions for a given event.  However, only the first return value that is not MPIMessageOK is returned by mpiControlProcessEvents.

Sample Code

Example C code:

void MPI_DECL2
    myEventCallback(MPIControl control, const MPIEventData* status, void* userData)
{
    /* print event type to screen. */

    printf("%s event occurred at controller sample %d.\n",
        mpiEventTypeName(status->eventType),
        status->data.sampleCounter);
}

Example C++ code:

void MPI_DECL2
    myEventCallback(MPIControl control, const MPIEventData* status, void* userData)
{
    // Exceptions must not propagate out of the callback function,
    // so all code is placed in a try-catch block.
    try
    {
        // print event type to screen
        std::cout << mpiEventTypeName(status->eventType)
                  << " event occurred at controller sample "
                  << status->data.sampleCounter
                  << '.' << std::endl;
    }
    catch(...) // Catch all exceptions
    {
    }
}

See Also

mpiControlEventCallbackAdd | mpiControlEventCallbackRemove | mpiControlProcessEvents | MPIEventData | MPIEventType | Event Overview