Base handle type of all reference counted CVB handles enabling shared ownership. An OBJ is an InterfaceContainer which aggregates multiple CVB interfaces by their base interface IDisposableType and manages their life-time:
When using a function which has a handle as a parameter, the InterfaceContainer queries the needed interface, like IImageVPA, if the function needs to access the image's properties or data. If the required interface is not in the container, the function will return false if the return type is cvbbool_t or CVC_ERROR( CVC_E_WRONGOBJECT )/CVC_ERROR( CVC_E_NOIMAGE ) if the return type is cvbres_t.
The InterfaceContainer holds the thread safe reference count and manages its life-time with it. The container is alive as long as the reference count is greater than zero. If the reference count reaches zero the container and its aggregated interface objects are destroyed.
Normally newly created objects have a reference count of 1. Every component that wants to take part in life-time management (uses the object) can share the handle via ShareObject and thus increase the reference count by 1. If the component does not need the object anymore, it releases the handle via ReleaseObject which will decrease the reference count by 1.
Note
The simple example above with the starting reference count of 1 does not hold true for complex objects like a driver loaded via LoadImageFile. The starting reference count is higher, but the rule that every call of a create function (like LoadImageFile) must be paired with one ReleaseObject call still is valid. In this case the reference count falls to zero even though the reference count was not 1!
Reference Count and Components
If you set e.g. an IMG 'object' into another component, it shares the given InterfaceContainer object holding the IImageVPA object. Components can be ActiveX Controls like the Display Active X control or the Foundation Package's FBlob tool. Any prior set IMG object is released on a successful set, thus automatically managing the life-time of the given IMG. That is the reason why you don't need to concern yourself too much with reference counting if you let the Image ActiveX control manage your images.
Note
A component storing an OBJ can itself be composed of multiple internal components (the Display ActiveX control is such an example). Thus setting an IMG object on a Display ActiveX control will increase the reference count by 2. If the Display ActiveX control is destroyed or a new image (or nullptr handle) is set, the old IMG object's reference count will also be decreased by two.
Attention
Never depend on the reference count in your application. The RefCount is only for debugging purposes! The exact values of such increases/decreases may change in a future version as the only contract is that each create or ShareObject call must be paired with exactly one ReleaseObject call.
The implementation changed to the form described above in CVB 2017 (13.00.000), but behaves exactly the same seen from the C-API. The change was from a IUnknown base interface to the InterfaceContainer and IDisposableType base interface.
Attention
Although incrementing/decrementing the reference count is thread safe, the associated operations may not necessarily be thread safe!
For example loading a Vin-driver or freeing it is not thread safe: Thus sharing and releasing handles is safe until you reach the reference count of 0. This results in the ReleaseObject function not being thread safe with drivers as you often cannot assure which is the last call to ReleaseObject. With a normal image created via CreateGenericImage, though, the ReleaseObject function is thread safe.
Verifies whether the given Image handle has an IGrabber object.
All devices that can produce image data provide this interface. Thus by calling this function on an IMG, you can determine whether you work with a pure or a driver image.
Note
Since CVB 2017 (13.00.000) this function always returns a correct result.
Parameters
[in]
Image
Object handle to be checked.
Returns
true if the object supports the IGrabber interface; false otherwise.
Returns the current value of the reference count for the given Object.
Note
This function only intended for debugging purposes. As described in the OBJ type, every create and ShareObject must be paired with a ReleaseObject.
This function is thread safe. But as an object may be released right after the call by another thread, you can not use this information in multi-threaded or production code. If you want to ensure a valid Object, use the ShareObject function. This function only succeeds on a valid object.
Attention
Production source code that depends on this function is fundamentally broken.
Increments the reference count of the given InterfaceContainerObject.
This function should be called when you store the Object in a component, like a class. Every call to this function must be paired with a call to ReleaseObject, when the object is not needed anymore (e.g. call this in the class destructor).
Note
Since CVB 2017 (13.00.000) this function always returns a correct result.
Parameters
[in]
Object
Object handle to InterfaceContainer.
Returns
true if reference count was incremented successfully; false otherwise.
This functionality is deprecated and in fact no longer supported by most of the current CVB Vin-drivers. Therefore it should no longer be used in an application.
Attention
This method is not implemented under non-Windows systems.
