DeviceManager Class Reference

Grants access to MATRIX VISION GmbH hardware. More...

#include <mvIMPACT_acquire.h>

List of all members.

Public Member Functions
unsigned int	changedCount (void) const
	Returns the current changed counter for the device list.
unsigned int	deviceCount (void) const
	Returns the number of devices currently present in the system.
	DeviceManager (const DeviceManager &src)
	Constructs a new mvIMPACT::acquire::DeviceManager object from an existing one.
	DeviceManager (void)
	Constructs a new mvIMPACT::acquire::DeviceManager object.
Device *	getDevice (unsigned int index) const
	Returns a pointer to a mvIMPACT::acquire::Device object.
Device *	getDeviceByFamily (const std::string &family="", unsigned int devNr=0, char wildcard= '*') const
	Tries to locate a device via the family name.
Device *	getDeviceByProduct (const std::string &product="", unsigned int devNr=0, char wildcard= '*') const
	Tries to locate a device via the product name.
Device *	getDeviceByProductAndID (const std::string &product="", unsigned int devID=0, char wildcard= '*') const
	Tries to locate a device via the product name and the device ID.
Device *	getDeviceBySerial (const std::string &serial="", unsigned int devNr=0, char wildcard= '*') const
	Tries to locate a device via the serial number.
DeviceManager &	operator= (const DeviceManager &rhs)
	Allows assignments of mvIMPACT::acquire::DeviceManager objects.
Device *	operator[] (unsigned int index) const
	Returns a pointer to a mvIMPACT::acquire::Device object.
void	updateDeviceList (void) const
	Updates the internal device list.
virtual	~DeviceManager (void)
	Class destructor.

---

Detailed Description

Grants access to MATRIX VISION GmbH hardware.

This class will grant access to any MATRIX VISION GmbH hardware installed on the current system. Whenever somewhere in the code a mvIMPACT::acquire::DeviceManager instance is created it can be used to access any MATRIX VISION GmbH device currently supported and available.

This is the only class, which is allowed to create instances of the class mvIMPACT::acquire::Device, which are needed to access a certain hardware device.

As a result of this every program written by the use of this interface will create an instance of mvIMPACT::acquire::DeviceManager before performing any other operations which uses object or functions from this interface.

During the construction of a mvIMPACT::acquire::DeviceManager object the system will be scanned for supported devices and once the instance has been created the object will always provide an up to date list of devices whenever the user asks for it.

This class also provides some functions to find a particular device in the system. Devices can e.g. be found by family or by serial number.

Note:

There always has to be at least one instance of the DeviceManager when the user still works with Device objects, as when the last instance to this object is destroyed all remaining Device objects will be closed automatically!

A mvIMPACT::acquire::DeviceManager object will initially return pointers to mvIMPACT::acquire::Device objects, which all seem to be closed. However one or more of the devices might have been opened by another instance of the device manager running in a different process. In that case the attempt to open a device, which seems to be closed will raise an exception with the error code mvIMPACT::acquire::DMR_DRV_ALREADY_IN_USE, which MUST be handled by the user.

Show C++ code Hide C++ code

C + +

 EXAMPLES:

    //-----------------------------------------------------------------------------
    void obtainDevicePointers( void )
    //-----------------------------------------------------------------------------
    {
      // Create an instance of the device manager to get access
      // to MATRIX VISION GmbH devices.
      DeviceManager devMgr;
   
      // show all devices
      for( unsigned int i=0; i<devMgr.deviceCount(); i++ )
      {
        cout << "Dev " << i << ": " << *(devMgr[i]) << endl;
      }
   
      // try to find a device using a special criteria 
      // ( some of these calls will fail!!! )
      // will fail as the string is not complete and does
      // NOT terminate with a wildcard.
      Device* pDev = devMgr.getDeviceBySerial( "SD0*0" );
      // might work if there are at least two devices with 
      // a matching serial number in the system.
      pDev = devMgr.getDeviceByFamily( "SD0*0*", 1 );
      // might work if there is at least one device whose type
      // specifying string starts with 'SampleDevi'.
      pDev = devMgr.getDeviceByProduct( "SampleDevi*" );
      // will fail as the string is not complete and does NOT
      // terminate with the user defined wildcard.
      pDev = devMgr.getDeviceByProduct( "SampleD*", 0, '$' );
      // will work if there is a device whose product name 
      // starts with 'SamplePro' and which has
      // been assigned the specified device ID.
      pDev = devMgr.getDeviceByProductAndID( "SamplePro*", 66, '*' );
      // will work if there is at least one device with a serial
      // number starting with 'SD00' in the system.
      pDev = devMgr.getDeviceBySerial( "SD00*" );
      // will return a pointer to the first device detected thus
      // this call will work if there is at least one device in the 
      // current system, that is supported by this interface
      pDev = devMgr.getDeviceBySerial( "*" );
      if( !pDev )
      {
        cout << "Error! No valid device found" << endl;
        return 0;
      }
   
      // from here it will be save to work with the pointer returned
      // by device manager.
      // THE NEXT LINE WILL TRY TO OPEN THE DEVICE! This can fail if the device
      // is already running in a different process!
      try
      {
        FunctionInterface func(pDev);
        // do some work
      }
      catch( const ImpactAcquireException& e )
      {
        // failed to open the device...
      }
    }
   
    //-----------------------------------------------------------------------------
    void showDeviceManagerOperation( void )
    //-----------------------------------------------------------------------------
    {
      Device* pDev = 0;
      {
        DeviceManager devMgr1;
        // will return a pointer to the first device detected thus
        // this call will work if there is at least one device in the 
        // current system, that is supported by this interface
        pDev = devMgr.getDeviceBySerial( "*" );
        if( !pDev )
        {
          cout << "Error! No valid device found" << endl;
          return 0;
        }
        // from here it will be save to work with the pointer returned
        // by device manager.
        // THE NEXT LINE WILL TRY TO OPEN THE DEVICE! This can fail if the device
        // is already running in a different process!
        try
        {
          FunctionInterface func(pDev);
          // do some work
        }
        catch( const ImpactAcquireException& e )
        {
          // failed to open the device...
        }
        {
          DeviceManager devMgr2;
          // This will return the same device as pDev
          Device* pDev2 = devMgr2.getDeviceBySerial( "*" );
        } // here the device manager devMgr2 will be destroyed, but it will NOT close pDev2, as devMgr1 holds a reference to it
        Statistics s(pDev); // this will still work
      } // here the last device manager will be destroyed, thus from here onwards pDev will be invalid!
      Info i(pDev); // this will chrash
      DeviceManager devMgr3;
      Info i2(devMgr3.getDevice(0)); // this will work again
    }
 

---

Constructor & Destructor Documentation

DeviceManager

(

void

)

[explicit]

Constructs a new mvIMPACT::acquire::DeviceManager object.

If the construction of this object fails for some reason this constructor might throw an exception of type mvIMPACT::acquire::ImpactAcquireException or a type derived from this class.

References mvIMPACT::acquire::DMR_NO_ERROR, mvIMPACT::acquire::INVALID_ID, and ExceptionFactory::raiseException().

DeviceManager

(

const DeviceManager &

src

)

[explicit]

Constructs a new mvIMPACT::acquire::DeviceManager object from an existing one.

If the construction of this object fails for some reason this constructor might throw an exception of type mvIMPACT::acquire::ImpactAcquireException or a type derived from this class.

References mvIMPACT::acquire::DMR_NO_ERROR, mvIMPACT::acquire::INVALID_ID, and ExceptionFactory::raiseException().

virtual ~DeviceManager

(

void

)

[virtual]

Class destructor.

There always has to be at least one instance of the DeviceManager when the user still works with mvIMPACT::acquire::Device objects, as when the last instance to this object is destroyed all remaining mvIMPACT::acquire::Device objects will be closed automatically!

---

Member Function Documentation

unsigned int changedCount

(

void

)

const

Returns the current changed counter for the device list.

This is a useful function to find out if the device list has been changed in any way. Such a change might be the appearance of a new USB device or a state change of any other device (e.g. when an USB device has been unplugged). Thus this function can be called periodically in order to maintain lists in GUI application for example. To find out the actual number of devices call mvIMPACT::acquire::DeviceManager::deviceCount.

Returns:

The current changed counter for the device list.

unsigned int deviceCount

(

void

)

const

Returns the number of devices currently present in the system.

This function returns the number of devices currently detected in the system. A device once connected to the system while the device manager was running will remain in its list even if it's unplugged (then only it's state will change). To detect changes in the mvIMPACT::acquire::DeviceManager objects list call the function mvIMPACT::acquire::DeviceManager::changedCount.

Returns:

The number of devices detected in the current system.

Device* getDevice

(

unsigned int

index

)

const

Returns a pointer to a mvIMPACT::acquire::Device object.

Returns a pointer to a mvIMPACT::acquire::Device object specifying the device found at the given index in the device managers internal list. Show C++ code Hide C++ code

C + +

 If the index is either equal or higher then the number of devices detected a STL out_of_range exception is thrown. 

See also:

DeviceManager::deviceCount,
DeviceManager::getDeviceBySerial,
DeviceManager::getDeviceByFamily,
DeviceManager::getDeviceByProduct

Returns:

• A pointer to the device if found.
  
• an invalid pointer or reference otherwise.

Parameters:

index

the index of the device to be returned

Device* getDeviceByFamily	(	const std::string &	family = "",
		unsigned int	devNr = 0,
		char	wildcard = '*'
	)			const

Tries to locate a device via the family name.

This function tries to find a device by its family (or parts of this family name). The user can specify only parts of the family name and a wildcard. The mvIMPACT::acquire::DeviceManager object will then try to find the device that matches these parameters in its current list. The family is the most general method of searching for a device apart from 'any device'. E.g. for a device the family name might be 'SampleDevice'

Show C++ code Hide C++ code

C + +

 EXAMPLES:

            // this will return a pointer to the second 'SampleDevice'
            // device found or 0 if there are no 2 'SampleDevice' 
            // devices in the system
            getDeviceByFamily( "SampleD*", 1, '*' );
            // will return a pointer to the first device belonging 
            // to the 'SampleDevice' family if present or 0.
            getDeviceByFamily( "SampleDevice" );
            // will return the first recognized device in the system
            getDeviceByFamily( "*", 0, '*' );
 

See also:

mvIMPACT::acquire::DeviceManager::getDeviceBySerial,
mvIMPACT::acquire::DeviceManager::getDeviceByProduct,
mvIMPACT::acquire::DeviceManager::getDeviceByProductAndID

Returns:

• A pointer to the device if found.
  
• an invalid pointer or reference otherwise.

Parameters:

family	The full family name of the requested device or known parts of it and wildcard characters
devNr	The number of the device to return (if there is more then one candidate)
wildcard	The character to ignore in family

Device* getDeviceByProduct	(	const std::string &	product = "",
		unsigned int	devNr = 0,
		char	wildcard = '*'
	)			const

Tries to locate a device via the product name.

This function tries to find a device by its product name (or parts of it). The user can specify only parts of the name and a wildcard. The mvIMPACT::acquire::DeviceManager object will then try to find the device that matches these parameters in its current list. The product name is a bit more specific then the family name, but less specific then the serial. For the 'SampleDevice' for example there might be different product names for different device types. This might e.g. be 'SampleDevice-G' for a grey version of the sample device and 'SampleDevice-C' for the color version of the sample device.

Show C++ code Hide C++ code

C + +

 EXAMPLES:

            // this will return a pointer to the second sample 
            // device of type 'G' found or 0 if there aren't 
            // two devices of this type in the system
            getDeviceByProduct( "SampleDevice-G", 1 );
            // will return a pointer to the first device whose 
            // product string starts with 'SampleDev' or 0 if 
            // no such device can be found.
            getDeviceByProduct( "SampleDev*", 0, '*' );
            // will return the first recognized device in the system
            getDeviceByProduct( "*", 0, '*' );
 

See also:

DeviceManager::getDeviceBySerial,
DeviceManager::getDeviceByFamily,
DeviceManager::getDeviceByProductAndID

Returns:

• A pointer to the device if found.
  
• an invalid pointer or reference otherwise.

Parameters:

product	The full product name of the requested device or known parts of it and wildcard characters
devNr	The number of the device to return (if there is more then one candidate)
wildcard	The character to ignore in product

Device* getDeviceByProductAndID	(	const std::string &	product = "",
		unsigned int	devID = 0,
		char	wildcard = '*'
	)			const

Tries to locate a device via the product name and the device ID.

This function behaves like mvIMPACT::acquire::DeviceManager::getDeviceByProduct except that the second parameter now is interpreted as the device ID.

Show C++ code Hide C++ code

C + +

 EXAMPLES:

            // this will return a pointer to the sample device of 
            // type 'G' which has been assigned a device ID of '1' 
            // or 0 if there is no sample device with this ID in the system.
            getDeviceByProductAndID( "SampleDevice-G", 1 );
            // will return a pointer to the device whose product string
            // starts with 'SampleDev' and whose device ID has been set
            // to '0' or 0 if no such device can be found.
            getDeviceByProductAndID( "SampleDev*", 0, '*' );
            // will return the first recognized device with an assigned 
            // device ID of '0' in the system.
            getDeviceByProductAndID( "*", 0 );
 

See also:

Device::deviceID,
DeviceManager::getDeviceByFamily,
DeviceManager::getDeviceByProduct,
DeviceManager::getDeviceBySerial,
Device::setID

Returns:

• A pointer to the device if found.
  
• an invalid pointer or reference otherwise.

Parameters:

product	The full product name of the requested device or known parts of it and wildcard characters
devID	The ID associated with this device.
wildcard	The character to ignore in product

Device* getDeviceBySerial	(	const std::string &	serial = "",
		unsigned int	devNr = 0,
		char	wildcard = '*'
	)			const

Tries to locate a device via the serial number.

This function tries to find a device by its serial number (or parts of this number). The user can specify only parts of the serial number and a wildcard. The mvIMPACT::acquire::DeviceManager object will then try to find that matches these parameters in its current list.

Show C++ code Hide C++ code

C + +

 EXAMPLES:

            // this will return a pointer to the second device with
            // a serial number starting with 'SD' device found or 0
            // if there are no 2 sample devices in the system
            getDeviceBySerial( "SD*******", 1, '*' );
            // will return a pointer to the device with the serial 
            // number SD000001 if present or 0
            getDeviceBySerial( "SD0000001" );
            // will return a pointer to the first device in the system
            getDeviceBySerial( "*", 0, '*' );
 

See also:

DeviceManager::getDeviceByFamily,
DeviceManager::getDeviceByProduct,
DeviceManager::getDeviceByProductAndID

Returns:

• A pointer to the device if found.
  
• an invalid pointer or reference otherwise.

Parameters:

serial	The full serial number or the known parts of the serial number and wildcard characters
devNr	The number of the device to return (if there is more then one candidate)
wildcard	The character to ignore in serial

DeviceManager& operator=

(

const DeviceManager &

rhs

)

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

Device* operator[]

(

unsigned int

index

)

const

Returns a pointer to a mvIMPACT::acquire::Device object.

Returns a pointer to a mvIMPACT::acquire::Device object specifying the device found at the given index in the device managers internal list. Show C++ code Hide C++ code

C + +

 If the index is either equal or higher then the number of devices detected

 a STL out_of_range exception is thrown. 

See also:

mvIMPACT::acquire::DeviceManager::deviceCount,
mvIMPACT::acquire::DeviceManager::getDeviceBySerial,
mvIMPACT::acquire::DeviceManager::getDeviceByFamily,
mvIMPACT::acquire::DeviceManager::getDeviceByProduct

Returns:

• A pointer to the device if found.
• an invalid pointer or reference otherwise.

Parameters:

index

the index of the device to be returned

void updateDeviceList

(

void

)

const

Updates the internal device list.

Most devices can't appear out of nowhere. For example a PCI device is either connected to the current system when the device manager is initialised or not but it will never appear at runtime after the DMR_Init() function has been called succesfully.

However certain device classes (e.g. network devices) might be connected to the system AFTER the device manager has been initialised. In order not to pollute the network or bus with constant rescan messages the user should call this function instead. This can either be done in reasonable intervals or after it is known that a new device has been connected to the system.

If new devices have been detected a subsequent call to mvIMPACT::acquire::DeviceManager::deviceCount will result in a higher value since a previous call.

References mvIMPACT::acquire::DMR_NO_ERROR, and ExceptionFactory::raiseException().

---

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

• mvIMPACT_acquire.h