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

#include <mvIMPACT_acquire.h>

Inheritance diagram for DeviceComponentLocator:

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.

HLIST	bindSearchBase (HLIST baselist, const std::string &pathToSearchBase="")
	Assign a new search base to the locator.

HLIST	bindSearchBaseList (Device *pDev, TDeviceListType deviceListType, const std::string &sublistName="")
	Assign a new search base to the locator.

unsigned int	changedCounter (void) const
	Returns the current changed counter for the component referenced by this object.

unsigned int	changedCounterAttr (void) const
	Returns the current attribute changed counter for the component referenced by this object.

	DeviceComponentLocator ()
	Constructs a new unbound locator.

	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.

	DeviceComponentLocator (HLIST baselist)
	Constructs a new bound to the specified base list locator.

	DeviceComponentLocator (HLIST baselist, const std::string &pathToSearchBase)
	Constructs a new locator and searches the search base list.

std::string	displayName (void) const
	Returns the display name of the component referenced by this object.

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.

HOBJ	hObj (void) const
	Returns a unique identifier for the component referenced by this object.

std::string	name (void) const
	Returns the name of the component referenced by this object.

	operator HOBJ () const
	Allows implicit conversion to a HOBJ.

HLIST	searchbase_id (void) const
	Returns the unique identifier of the base list from where to start searching for a component.

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.

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

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

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 );
  }
}

Examples: FirmwareUpdate.cpp, GenericInterfaceLayout.cpp, GenericInterfaceLayout.legacy.cpp, GigEVisionActionFeatures.cpp, Properties.cpp, and Properties.legacy.cpp.

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] baselist A 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]	baselist	A unique identifier to the base list from where to start to search for the search base.
[in]	pathToSearchBase	The 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]	pDev	A pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]	deviceListType	The type list to locate
[in]	sublistName	A 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]	access	The access object to bind to the driver object.
[in]	name	The path and/or name of the object to be located.
[in]	searchMode	Specifies how and what to search for. Valid flags(these flags can be combined using the '\|' operator) for this parameter are: - smIgnoreLists - smIgnoreMethods - smIgnoreProperties
[in]	maxSearchDepth	The 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.

Examples: GigEVisionActionFeatures.cpp.

◆ 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]	baselist	A unique identifier for the base list used to start searching the search base.
[in]	pathToSearchBase	The 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]	pDev	A pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]	deviceListType	The type list to locate
[in]	sublistName	The 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
//-----------------------------------------------------------------------------
{
  mvIMPACT::acquire::Component c_;
  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;
    }
  }
}

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

	query	The type of the parameter to read
[in]	param1	An additional parameter
[in]	param2	An 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: GenICamSequencerParameterChangeAtRuntime.cpp, GenICamSequencerUsage.cpp, GenICamSequencerUsage.legacy.cpp, GenICamSequencerUsageWithPaths.cpp, GenICamSequencerUsageWithPaths.legacy.cpp, and 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]	name	The path and/or name of the object to be located.
[in]	searchMode	Specifies how and what to search for. Valid flags(these flags can be combined using the '\|' operator) for this parameter are: - smIgnoreLists - smIgnoreMethods - smIgnoreProperties
[in]	maxSearchDepth	The 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.

◆ 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.

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

Constructor & Destructor Documentation

◆ DeviceComponentLocator() [1/4]

◆ DeviceComponentLocator() [2/4]

◆ DeviceComponentLocator() [3/4]

◆ DeviceComponentLocator() [4/4]

Member Function Documentation

◆ bindComponent()

◆ bindSearchBase()

◆ bindSearchBaseList()

◆ changedCounter()

◆ changedCounterAttr()

◆ compGetStringParam()

◆ displayName()

◆ findComponent()

◆ hObj()

◆ name()

◆ operator HOBJ()

◆ searchbase_id()

◆ stringAllocator()

Member Data Documentation

◆ m_hObj