mvIMPACT Acquire SDK C++
ComponentCallback Class Reference

A simple helper class to wrap the creation of a callback object. More...

Public Member Functions

 ComponentCallback (const ComponentCallback &src)
 Copy constructor. More...
 ComponentCallback (void *pUserData=0)
 Creates a new mvIMPACT::acquire::ComponentCallback instance. More...
virtual void execute (Component &, void *)
 The callback function. More...
bool isComponentRegistered (Component c) const
 Checks if a component is currently registered for this callback or not. More...
ComponentCallbackoperator= (const ComponentCallback &rhs)
 Allows assignments of mvIMPACT::acquire::ComponentCallback objects. More...
bool registerComponent (Component c)
 Registers a component for this callback. More...
bool unregisterComponent (Component c)
 Unregisters a component for this callback. More...
virtual ~ComponentCallback ()
 Class destructor. More...

Detailed Description

A simple helper class to wrap the creation of a callback object.

Applications need to derive from this class and must re-implement the function mvIMPACT::acquire::ComponentCallback::execute.

By deriving from this class it will become possible to receive a notification whenever an object derived from mvIMPACT::acquire::Component has changed. So e.g. an application could register a callback on the mvIMPACT::acquire::Device::state property to get notified when e.g. a certain device has been unplugged or restarted.

A change is not necessarily a changed value of a property but also any other change in behaviour like a change in visibility or availability. So when a callback has been registered for a certain read-only component that becomes writable for some reason the registered callback would be executed as well.

A single instance of an object derived from this class can hold an arbitrary number of components which are monitored. components can be registered by calling the mvIMPACT::acquire::ComponentCallback::registerComponent function, so it is not necessary to create and hold a callback instance for every feature that shall be monitored. Since when the callback is executed the information about the object that has triggered it will be supplied as one the input parameters it is easy to decide what has to be done.

Reading and understanding the documentation supplied with the mvIMPACT::acquire::ComponentCallback::execute function is vital to write error-free code!
It is NOT save to call mvIMPACT::acquire::ComponentCallback::registerComponent and mvIMPACT::acquire::ComponentCallback::unregisterComponent from parallel threads! If this is absolutely necessary appropriate synchronization code must be wrapped around these calls by the calling code!

Constructor & Destructor Documentation

◆ ComponentCallback() [1/2]

ComponentCallback ( void *  pUserData = 0)

Creates a new mvIMPACT::acquire::ComponentCallback instance.

[in]pUserDataA pointer to user specific data bound to this callback. This data will be passed back to the user whenever the callback function gets executed and can be used to attach custom data to the callback function.

◆ ComponentCallback() [2/2]

ComponentCallback ( const ComponentCallback src)

Copy constructor.

Creates a new object from an existing device object. Keep in mind that this new object will provide access to the very same objects. This constructor is only provided for internal reference counting to guarantee correct operation of the objects of this class under all platforms and languages.

◆ ~ComponentCallback()

virtual ~ComponentCallback ( )

Class destructor.

This will automatically unregister all components still referencing this callback and will free all internal resources.

Member Function Documentation

◆ execute()

virtual void execute ( Component ,
void *   

The callback function.

Re-implement this function in a derived class in order to implement a custom behaviour.

Please note that this function will be executed within the thread context that is causing this callback, thus by any thread belonging to the internal device driver instance. There is a high chance that this is a different thread than any known to by the application, thus appropriate mechanisms to ensure correct execution must be implemented by an application(e.g. GUI applications might send an event to the main thread instead of directly accessing GUI elements from here).

As each device driver instance internally creates multiple threads and since components can be modified by the driver framework from any of these threads, the thread context might in fact be different each time this function gets called. Accessing data from objects that are inherited from mvIMPACT::acquire::Component is thread safe so e.g. property values can be read out in parallel securely! However this 'execute' in a worst case (when several components have been registered to a single callback) might in fact be called in parallel so everything that happens in here should be designed accordingly!

It is NOT recommended to do time consuming stuff here! This function should be considered as something like an interrupt instead: Just take a note about what did just happen and leave. The calling thread will block until this function does return which might have all sorts of consequences if this takes a lot of time. In the worst case e.g. image data might get lost!

GenICam event specific: When dealing with GenICam device events from a single device only within this callback due to the internal design it is guaranteed that this callback will NOT be executed in parallel since the device events will be received sequentially and will always be reported by the same (device driver instance related) thread! So when e.g. registering for changes to the following properties:

◆ isComponentRegistered()

bool isComponentRegistered ( Component  c) const

Checks if a component is currently registered for this callback or not.

  • true if the component currently is registered for this callback
  • false otherwise
[in]cThe component that shall be tested against this callback

◆ operator=()

ComponentCallback& operator= ( const ComponentCallback rhs)

Allows assignments of mvIMPACT::acquire::ComponentCallback objects.

◆ registerComponent()

bool registerComponent ( Component  c)

Registers a component for this callback.

  • true if the component could be registered successfully for this callback.
  • false otherwise
[in]cThe component to register for this callback

◆ unregisterComponent()

bool unregisterComponent ( Component  c)

Unregisters a component for this callback.

  • true if the component could be unregistered successfully for this callback.
  • false otherwise
[in]cThe component to unregister from this callback

The documentation for this class was generated from the following file: