mvIMPACT Acquire SDK C++
DeviceComponentLocator Class Reference

A class to locate components within the driver. More...

Inheritance diagram for DeviceComponentLocator:
ComponentLocatorBase ComponentAccess

Public Member Functions

bool bindComponent (Component &access, const std::string &name, int searchMode=0, int maxSearchDepth=INT_MAX) const
 Binds an access object to an internal driver object. More...
 
HLIST bindSearchBase (HLIST baselist, const std::string &pathToSearchBase="")
 Assign a new search base to the locator. More...
 
HLIST bindSearchBaseList (Device *pDev, TDeviceListType deviceListType, const std::string &sublistName="")
 Assign a new search base to the locator. More...
 
unsigned int changedCounter (void) const
 Returns the current changed counter for the component referenced by this object. More...
 
unsigned int changedCounterAttr (void) const
 Returns the current attribute changed counter for the component referenced by this object. More...
 
 DeviceComponentLocator ()
 Constructs a new unbound locator. More...
 
 DeviceComponentLocator (Device *pDev, TDeviceListType deviceListType, const std::string &sublistName="")
 Constructs a new locator and bind the search base to the specified list type of the device. More...
 
 DeviceComponentLocator (HLIST baselist)
 Constructs a new bound to the specified base list locator. More...
 
 DeviceComponentLocator (HLIST baselist, const std::string &pathToSearchBase)
 Constructs a new locator and searches the search base list. More...
 
std::string displayName (void) const
 Returns the display name of the component referenced by this object. More...
 
HOBJ findComponent (const std::string &name, int searchMode=0, int maxSearchDepth=INT_MAX) const
 Tries to locate a certain component in a hierarchy of components. More...
 
HOBJ hObj (void) const
 Returns a unique identifier for the component referenced by this object. More...
 
std::string name (void) const
 Returns the name of the component referenced by this object. More...
 
 operator HOBJ () const
 Allows implicit conversion to a HOBJ. More...
 
HLIST searchbase_id (void) const
 Returns the unique identifier of the base list from where to start searching for a component. More...
 

Protected Types

enum  { BUFFER_INCREMENT_FACTOR = 6 }
 An internal constant that defines by which factor dynamic buffers will grow when the current size is not sufficient. More...
 

Protected Member Functions

std::string compGetStringParam (TOBJ_StringQuery query, int param1=0, int param2=0) const
 A helper function to query certain component related string parameters. More...
 

Static Protected Member Functions

static char * stringAllocator (const char *pBuf, size_t reqBufSize)
 An internal helper function for fast string allocation. More...
 

Protected Attributes

HOBJ m_hObj
 A unique identifier for the internal driver object referenced by this instance of mvIMPACT::acquire::ComponentAccess. More...
 

Detailed Description

A class to locate components within the driver.

Every driver will offer a set of properties, methods and component lists. mvIMPACT::acquire::Property objects contain data such as the current gain in dB, the state of a digital input, etc.. mvIMPACT::acquire::Method objects can be executed like a normal function and mvIMPACT::acquire::ComponentList objects are used to group certain objects together to form a logical unit.

When it's necessary to locate one or more of these objects without knowing exactly where to look for them this locator class can be used to look for the component.

In general the properties interesting for the user can be found in one of the classes offered by this interface, but when a special property is needed or a new property that hasn't been embedded into the C++ interface, this class offers a way to get hold of its handle.

// assuming a new property 'MyProp' has been added to the setting of a
// device driver whose product string is 'MyDevice' and it has not been
// added to the corresponding class or the property shall be accessed
// without rebuilding the application.
// The latter situation will require some kind of interpreter that
// can pass the required information to the device driver
//-----------------------------------------------------------------------------
enum TMyEnumType
//-----------------------------------------------------------------------------
{
metOne = 0,
metTwo,
metThree
};
//-----------------------------------------------------------------------------
void fn( void )
//-----------------------------------------------------------------------------
{
DeviceManager devMgr;
Device* pDev = devMgr.getDeviceByProduct( "MyDev*" );
if( pDev )
{
// get access to the base setting
DeviceComponentLocator locator( pDev, dltSetting, "Base" );
Property prop;
locator.bindComponent( prop, "MyProp" );
// set the value by string
prop.writeS( "MyVal" );
if( prop.type() == ctPropInt )
{
PropertyI iProp( prop.hObj() );
int myVal = 666;
iProp.write( myVal );
}
// if the type is known this test can be omitted:
PropertyF fProp;
locator.bindComponent( fProp, "MyFloatProperty" );
fProp.write( 3.14 );
// When it's an enumerated property this is legal as well:
PropertyIMyEnumType eProp;
locator.bindComponent( eProp, "MyEnumeratedProperty" );
eProp.write( metOne );
}
}
DeviceComponentLocator()
Constructs a new unbound locator.
Definition: mvIMPACT_acquire.h:7853
const EnumPropertyF & write(ZYX value, int index=0) const
Writes one value to the property.
Definition: mvIMPACT_acquire.h:3837
EnumPropertyI< int > PropertyI
A type for integer properties.
Definition: mvIMPACT_acquire.h:4516
EnumPropertyF< double > PropertyF
A type for floating point properties.
Definition: mvIMPACT_acquire.h:3911
@ dltSetting
Specifies a certain setting.
Definition: mvIMPACT_acquire.h:7616
@ ctPropInt
Defines a property for 32 bit integer values.
Definition: mvPropHandlingDatatypes.h:347

Member Enumeration Documentation

◆ anonymous enum

anonymous enum
protectedinherited

An internal constant that defines by which factor dynamic buffers will grow when the current size is not sufficient.

Enumerator
BUFFER_INCREMENT_FACTOR 

Constructor & Destructor Documentation

◆ DeviceComponentLocator() [1/4]

DeviceComponentLocator ( )
inlineexplicit

Constructs a new unbound locator.

◆ DeviceComponentLocator() [2/4]

DeviceComponentLocator ( HLIST  baselist)
inlineexplicit

Constructs a new bound to the specified base list locator.

Parameters
[in]baselistA unique identifier to the base list from where to start to search for the search base.

◆ DeviceComponentLocator() [3/4]

DeviceComponentLocator ( HLIST  baselist,
const std::string &  pathToSearchBase 
)
inlineexplicit

Constructs a new locator and searches the search base list.

Parameters
[in]baselistA unique identifier to the base list from where to start to search for the search base.
[in]pathToSearchBaseThe name or path ('/' separated) to the search base.

◆ DeviceComponentLocator() [4/4]

DeviceComponentLocator ( Device pDev,
TDeviceListType  deviceListType,
const std::string &  sublistName = "" 
)
inlineexplicit

Constructs a new locator and bind the search base to the specified list type of the device.

Parameters
[in]pDevA pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]deviceListTypeThe type list to locate
[in]sublistNameA string that can contain the name of the list if there is more than one candidate (e.g. when looking for settings)

Member Function Documentation

◆ bindComponent()

bool bindComponent ( Component access,
const std::string &  name,
int  searchMode = 0,
int  maxSearchDepth = INT_MAX 
) const
inlineinherited

Binds an access object to an internal driver object.

Returns
  • true if successful
  • false otherwise. In case false is returned by this function the component could not be bound, which means subsequent calls using access will fail or throw an exception.
Parameters
[in,out]accessThe access object to bind to the driver object.
[in]nameThe path and/or name of the object to be located.
[in]searchModeSpecifies how and what to search for. Valid flags(these flags can be combined using the '|' operator) for this parameter are: - smIgnoreLists - smIgnoreMethods - smIgnoreProperties
[in]maxSearchDepthThe maximum depth (in lists) where to search for the component. By e.g. setting this value to 2, the current list and all its sub lists will be searched for the object, but no sublists of sub lists. -1 will search in ALL sub lists.

◆ bindSearchBase()

HLIST bindSearchBase ( HLIST  baselist,
const std::string &  pathToSearchBase = "" 
)
inlineinherited

Assign a new search base to the locator.

This new search base will be searched starting from the base list specified.

Returns
The unique identifier of the new search base.
Parameters
[in]baselistA unique identifier for the base list used to start searching the search base.
[in]pathToSearchBaseThe name or path to the search base.

◆ bindSearchBaseList()

HLIST bindSearchBaseList ( Device pDev,
TDeviceListType  deviceListType,
const std::string &  sublistName = "" 
)
inline

Assign a new search base to the locator.

This new search base will be search starting from the base list specified.

Returns
The unique identifier of the new search base.
Parameters
[in]pDevA pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]deviceListTypeThe type list to locate
[in]sublistNameThe name or path to the search base.

◆ changedCounter()

unsigned int changedCounter ( void  ) const
inlineinherited

Returns the current changed counter for the component referenced by this object.

This changed counter is incremented internally each time the component is modified. To check if this component has been modified since the last time, this check has been performed, keep track of the last return value of this function and compare it with the new value. This can be helpful e.g. to keep a GUI up to date. The value returned by this function will always be larger than or equal to the value returned by mvIMPACT::acquire::ComponentAccess::changedCounterAttr (except in case of a wrap around) when called at the same time for the same object as it's always incremented when the component has been modified in any way while the latter one will only be incremented if the attributes (e.g. the flags) but NOT if e.g. the value(s) of a property has been modified.

//-----------------------------------------------------------------------------
struct ComponentRef
//-----------------------------------------------------------------------------
{
unsigned int lastChangedCount_;
ComponentRef( mvIMPACT::acquire::Component c ) : c_( c ), lastChangedCount_( 0 ) {}
};
//-----------------------------------------------------------------------------
void fn( ComponentRef& cr )
//-----------------------------------------------------------------------------
{
if( cr.c_.isValid() )
{
const unsigned int currentChangedCount = cr.c_.changedCounter();
if( currentChangedCount != cr.lastChangedCount_ )
{
// something has happened since the last check!
doWhatNeedsToBeDone();
// and remember the current changed counter
cr.lastChangedCount_ = currentChangedCount;
}
}
}
A base class to implement access to internal driver components.
Definition: mvIMPACT_acquire.h:1321
Returns
The current changed counter of this object.

◆ changedCounterAttr()

unsigned int changedCounterAttr ( void  ) const
inlineinherited

Returns the current attribute changed counter for the component referenced by this object.

This changed counter is incremented internally each time the components attributes have been modified. To check if this components attributes have been modified since the last time, this check has been performed, keep track of the last return value of this function and compare it with the new value. This can be helpful e.g. to keep a GUI up to date.

Note
Attributes changes are e.g. a modification to a property's translation dictionary, but NOT a property's value. Because of this the value returned by this function will always be less or equal than the value returned by the function mvIMPACT::acquire::ComponentAccess::changedCounter (except in case of a wrap around) when called at the same time for the same object.
See also
mvIMPACT::acquire::ComponentAccess::changedCounter
Returns
The current attributes changed counter of this object.

◆ compGetStringParam()

std::string compGetStringParam ( TOBJ_StringQuery  query,
int  param1 = 0,
int  param2 = 0 
) const
inlineprotectedinherited

A helper function to query certain component related string parameters.

This function might throw an exception, if an invalid parameter has been queried.

Returns
A string containing the data to be queried.
Parameters
queryThe type of the parameter to read
[in]param1An additional parameter
[in]param2An additional parameter

◆ displayName()

std::string displayName ( void  ) const
inlineinherited

Returns the display name of the component referenced by this object.

Since
1.11.20
Returns
The display name of the component referenced by this object. This might be an empty string if no display name has been specified.
Examples
exampleHelper.h.

◆ findComponent()

HOBJ findComponent ( const std::string &  name,
int  searchMode = 0,
int  maxSearchDepth = INT_MAX 
) const
inlineinherited

Tries to locate a certain component in a hierarchy of components.

Returns
A unique identifier to the component if found or mvIMPACT::acquire::INVALID_ID if the component couldn't be found.
Parameters
[in]nameThe path and/or name of the object to be located.
[in]searchModeSpecifies how and what to search for. Valid flags(these flags can be combined using the '|' operator) for this parameter are: - smIgnoreLists - smIgnoreMethods - smIgnoreProperties
[in]maxSearchDepthThe maximum depth (in lists) where to search for the component. By e.g. setting this value to 2, the current list and all its sub lists will be searched for the object, but no sublists of sub lists. -1 will search in ALL sub lists.

◆ hObj()

HOBJ hObj ( void  ) const
inlineinherited

Returns a unique identifier for the component referenced by this object.

Returns
A unique identifier for the component referenced by this object.

◆ name()

std::string name ( void  ) const
inlineinherited

Returns the name of the component referenced by this object.

Returns
The name of the component referenced by this object.
Examples
exampleHelper.h.

◆ operator HOBJ()

operator HOBJ ( ) const
inlineinherited

Allows implicit conversion to a HOBJ.

◆ searchbase_id()

HLIST searchbase_id ( void  ) const
inlineinherited

Returns the unique identifier of the base list from where to start searching for a component.

Returns
The unique identifier of the base list from where searching for a component will start currently.

◆ stringAllocator()

static char* stringAllocator ( const char *  pBuf,
size_t  reqBufSize 
)
inlinestaticprotectedinherited

An internal helper function for fast string allocation.

Member Data Documentation

◆ m_hObj

HOBJ m_hObj
protectedinherited

A unique identifier for the internal driver object referenced by this instance of mvIMPACT::acquire::ComponentAccess.


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