Device Class Reference

This class and its functions represent an actual device detected by this interface in the current system. More...

#include <mvIMPACT_acquire.h>

List of all members.

Public Member Functions

void close (void)
 Closes an opened device.
 Device (const Device &src)
 Copy constructor.
UserData & getUserData (void)
 Returns a reference to a helper class to handle user specific data stored in the devices non-volatile memory(if available).
bool hasCapability (TDeviceCapability capability) const
 Checks whether this device has a certain capability.
HDEV hDev (void) const
 A unique identifier for this device.
HDRV hDrv (void) const
 A unique identifier for the functionality offered by this device.
bool isOpen (void) const
 Returns the current initialisation status in this process.
void open (void)
 Opens a device.
Device & operator= (const Device &rhs)
 Allows assignments of mvIMPACT::acquire::Device objects.
int setID (int newID) const
 Assigns a new ID to this device.
int updateFirmware (void) const
 Updates the firmware of the device.
 ~Device (void)
 Class destructor.

Public Attributes

PropertyIDeviceCapability capabilities
PropertyS customDataDirectory
 A string property (read-only once the device is open) containing a path to a custom directory for the location of camera description files, etc.
PropertyIDeviceClass deviceClass
 An enumerated integer property (read-only) defining the device class this device belongs to.
PropertyI deviceID
 A integer property (read-only) containing the device ID associated with this device.
PropertyS family
 A string property (read-only) containing the family name of this device.
PropertyI firmwareVersion
 An integer property (read-only) containing the firmware version of this device.
PropertyIHWUpdateResult HWUpdateResult
 An enumerated integer property (read-only) defining user executed hardware update results.
PropertyIDeviceInterfaceLayout interfaceLayout
 An enumerated integer property which can be used to define which interface layout shall be used when the device is opened.
PropertyIDeviceLoadSettings loadSettings
 An enumerated integer property which can be used to define which previously stored setting to load when the device is opened.
PropertyS product
 A string property (read-only) containing the product name of this device.
PropertyS serial
 A string property (read-only) containing the serial number of this device.
PropertyIDeviceState state
 An enumerated integer property (read-only) containing the current state of this device.

Detailed Description

This class and its functions represent an actual device detected by this interface in the current system.

Instances of it can only be created by instances of the mvIMPACT::acquire::DeviceManager class as only the mvIMPACT::acquire::DeviceManager has the precise knowledge to do that anyway. As a result from this fact pointers to instances of mvIMPACT::acquire::Device can be obtained via a mvIMPACT::acquire::DeviceManager object only.

A valid pointer to a mvIMPACT::acquire::Device object is needed to construct most of the other objects available in this interface.

Almost every object requiering a valid pointer to a mvIMPACT::acquire::Device object will need to device in an initialised state as the properties provided e.g. by the class mvIMPACT::acquire::CameraSettingsBase will be constructed when the device is initialised. To initialise a device this class provides the function Device::open. However every object which needs an initialised device to be constructed successfully will try to open the device when it hasn't been opened before, so the user does not need to call this function explicitly.

Note:
IMPORTANT: Whenever a device is closed via a call to mvIMPACT::acquire::Device::close all other objects constructed with a pointer to that device before will become invalid an need to be reconstructed afterwards, so don't close a device needlessly.

IMPORTANT: Whenever the last instance to a DeviceManager object get's destroyed within the program every remaining device will be closed automatically! Thus every instance to mvIMPACT::acquire::Device objects or objects created with a pointer to a mvIMPACT::acquire::Device object will become invalid automatically. Therefore the user has to make sure there is always at least one instance to a mvIMPACT::acquire::DeviceManager object within the current process!

Constructor & Destructor Documentation

Device ( const Device &  src  )  [explicit]

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 hardware and therefore you might as well use the original reference returned from the mvIMPACT::acquire::DeviceManager. This constructor is only provided for internal reference counting to guarantee correct operation of the objects of this class under all platforms and languages.

~Device ( void   ) 

Class destructor.

Note:
This destuctor must only be called for objects that have been created directly by the user on unmanaged heaps. Under most circumstances this means NEVER.

Member Function Documentation

void close ( void   ) 

Closes an opened device.

This function closes a device previously opened again.

See also:
Device::open,
Device::isOpen

UserData& getUserData ( void   ) 

Returns a reference to a helper class to handle user specific data stored in the devices non-volatile memory(if available).

Returns:
A reference to a helper class to handle user specific data stored in the devices non-volatile memory(if available).

bool hasCapability ( TDeviceCapability  capability  )  const

Checks whether this device has a certain capability.

Returns:
  • true if the device has the capability in question
  • false otherwise.

HDEV hDev ( void   )  const

A unique identifier for this device.

Note:
This handle is NOT to be confused with the id stored in the devices EEPROM The latter one represents a number stored somewhere in the physical devices EEPROM, while this handle can be assumed as a handle from a software based point of view.

HDRV hDrv ( void   )  const

A unique identifier for the functionality offered by this device.

Note:
This identifier is only valid, if the device has been initialised before by a call to Device::open

bool isOpen ( void   )  const

Returns the current initialisation status in this process.

If this function returns true, this only states, that the current process has not opened the device in question already. A call to mvIMPACT::acquire::Device::open() can still fail because of some other process using this device.

See also:
Device::open,
Device::close
Returns:
  • true if the device is initialised(opened) in the current process.
  • false otherwise.

void open ( void   ) 

Opens a device.

This function will try to open the device represented by this instance of mvIMPACT::acquire::Device. If this fails for any reason an exception will be thrown. The exception object will contain additional information about the reason for the error.

Calling this function is not really necessary, as each object for accessing other settings of the device or even the function interface need the device to be opened in order to be constructed. Therefore all the constructors for these objects check if the device is open by calling mvIMPACT::acquire::Device::isOpen and open the Device if necessary.

Note:
Keep in mind that the first object trying to open the device might therefore throw an exception as well when opening the devices fails for some reason.

Device& operator= ( const Device &  rhs  ) 

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

int setID ( int  newID  )  const

Assigns a new ID to this device.

To allow any application to distinguish between different devices of the same type the user can assign an unique ID to each device using this function. This ID currently is limited to values between 0 and 250 and is stored in the devices internal memory. This ID is NOT volatile. It will remain stored even if the device is unplugged.

Note:
REMARKS:

  • The device must be closed to assign a new ID.
  • This ID is not to be confused with the handle returned by the function mvIMPACT::acquire::Device::hDev. The latter one represents something which can be assumed as a handle from a software based point of view, while the ID represented by the property mvIMPACT::acquire::Device::deviceID is an ID stored in the physical devices EEPROM.
  • Not every device will offer this feature! When calling this function for a device, that does not offer this feature the function will return mvIMPACT::acquire::DMR_FEATURE_NOT_AVAILABLE.
See also:
mvIMPACT::acquire::Device::open,
mvIMPACT::acquire::Device::close
Returns:

int updateFirmware ( void   )  const

Updates the firmware of the device.

calling this function will cause the driver to download the firmware version compiled into the driver library into the physical devices EEPROM.

Note:
REMARKS:

  • Be sure what you are doing before calling this function. Under normal circumstances it won't be necessary to update a devices firmware.
  • The download will take some time (depending on the device up to 30 seconds). During this time the device and the thread calling this function will NOT respond.
  • Do NOT interrupt this download.
  • After a successful download a USB device needs to be unplugged and plugged in again. Otherwise the new firmware version will not be activated.
  • To download a new firmware version the device must be closed.
  • Not every device will offer this feature! When calling this function for a device, that does not offer this feature the function will return mvIMPACT::acquire::DMR_FEATURE_NOT_AVAILABLE.
See also:
mvIMPACT::acquire::Device::open,
mvIMPACT::acquire::Device::close
Returns:

Member Data Documentation

PropertyIDeviceCapability capabilities

PropertyS customDataDirectory

A string property (read-only once the device is open) containing a path to a custom directory for the location of camera description files, etc.

When a custom path is assigned to this property this path will be used to locate certain driver specific files and folders. Under this folder the following structure must be created:

            <customDataDirectory>
                |- CameraFiles  // this folder will be searched by frame grabbers for camera description files
                |- GenICam      // this folder will be searched by GenICam compliant devices, that refer to a local GenICam&trade; description file

If this property is left empty 

            %ALL USERS%\Documents\MATRIX VISION\mvIMPACT acquire
will be used by default on Windows™ platforms and 
            /etc/matrix-vision/mvimpact-acquire
on Linux platforms.

PropertyIDeviceClass deviceClass

An enumerated integer property (read-only) defining the device class this device belongs to.

Note:
This property has been added to the device driver in version 1.8.3 thus might not be available when working with old device drivers. Therefore always call the function mvIMPACT::acquire::Component::isValid to check if this property is available or not.

PropertyI deviceID

A integer property (read-only) containing the device ID associated with this device.

A device ID can be used to identify a certain device in the system. The ID is an 8 bit unsigned integer value stored in the devices EEPROM. In order to allow the detection of a device distinct detection of a device via its device ID the user has to make sure, that two devices belonging to the same product family never share the same ID.

Note:
REMARKS:

  • To modify the device ID a separate tool will be provided. To modify the device ID without that tool the function mvIMPACT::acquire::Device::setID can be called.
  • This ID is not to be confused with the handle returned by the function mvIMPACT::acquire::Device::hDev. The latter one represents something which can be assumed as a handle from a software based point of view, while the ID represented by the property deviceID is an ID stored in the physical devices EEPROM.

PropertyS family

A string property (read-only) containing the family name of this device.

PropertyI firmwareVersion

An integer property (read-only) containing the firmware version of this device.

PropertyIHWUpdateResult HWUpdateResult

An enumerated integer property (read-only) defining user executed hardware update results.

This property e.g. might contain the result of a user executed firmware update. Valid values for this property are defined by the enumeration mvIMPACT::acquire::THWUpdateResult.

PropertyIDeviceInterfaceLayout interfaceLayout

An enumerated integer property which can be used to define which interface layout shall be used when the device is opened.

Valid values for this property are defined by the enumeration mvIMPACT::acquire::TDeviceInterfaceLayout.

Note:
Once the device is in use (has been initialized) this property will become (read-only).

This feature is available for every device. A device not offering this feature requires a driver update. Always check for the availability of this feature by calling mvIMPACT::acquire::Component::isValid.

Not every device will offer the same options. Check for valid modes by reading the properties translation dictionary with the functions mvIMPACT::acquire::PropertyIDeviceInterfaceLayout::getTranslationDictString and mvIMPACT::acquire::PropertyIDeviceInterfaceLayout::getTranslationDictValue. Show C++ code

PropertyIDeviceLoadSettings loadSettings

An enumerated integer property which can be used to define which previously stored setting to load when the device is opened.

Valid values for this property are defined by the enumeration mvIMPACT::acquire::TDeviceLoadSettings.

Note:
Once the device is in use (has been initialized) this property will become (read-only).

PropertyS product

A string property (read-only) containing the product name of this device.

PropertyS serial

A string property (read-only) containing the serial number of this device.

PropertyIDeviceState state

An enumerated integer property (read-only) containing the current state of this device.

The state e.g. tells the user if an USB device is currently unplugged or not. Valid values for this property are defined by the enumeration mvIMPACT::acquire::TDeviceState.

The documentation for this class was generated from the following file:
MATRIX VISION
Generated on Fri Jun 5 14:26:01 2009