mvIMPACT Acquire SDK C++
UserData Class Reference

A helper class to work with the device specific non-volatile memory(if available). More...

Public Member Functions

UserDataEntry createEntry (void)
 Creates and returns a new entry to store user specific data. More...
 
void deleteEntry (UserDataEntry &userDataEntry)
 Deletes an entry of user specific data. More...
 
int getFreeMemory (void) const
 Returns the number of bytes of user accessible, non-volatile memory that is still available. More...
 
UserDataEntry getUserDataEntry (int nr) const
 Returns An object to work with an existing entry of user specific data. More...
 
bool isAvailable (void) const
 This function should be called to check if this device offers non-volatile memory that can be accessed by the user. More...
 
void validUserDataEntryIndexes (std::vector< int > &sequence) const
 Fills an array with all currently valid user data entry indexes. More...
 
void writeToHardware (void) const
 Writes the current set of user data into the devices non-volatile memory. More...
 

Public Attributes

PropertyI memoryAvailable_bytes
 An integer property (read-only) containing the number of bytes of user accessible, non-volatile memory this device has available. More...
 
PropertyI memoryConsumed_bytes
 An integer property (read-only) containing the number of bytes of user accessible, non-volatile memory currently consumed by user data. More...
 
PropertyIUserDataReconnectBehaviour reconnectBehaviour
 An enumerated integer property that can be used to configure how the user data should be treated in case of a device that has been unplugged is plugged back in again. More...
 

Friends

class Device
 

Detailed Description

A helper class to work with the device specific non-volatile memory(if available).

A device might have a certain amount of non-volatile memory which can be accessed and modified by the user. This data can e.g. be used to store certain parameters or custom data permanently into the device. Thus this property e.g. can be used to store configuration data in the device before shipping it to the end user.

In theory the number of entries that can be stored in the device is not limited. However no device will provide an unlimited amount of memory.

Writing data to any property of a mvIMPACT::acquire::UserDataEntry as well as creating a new entry by calling mvIMPACT::acquire::UserData::createEntry or deleting an entry with the function mvIMPACT::acquire::UserData::deleteEntry will NOT automatically result in the complete data to be updated in the device specific memory. As writing to the device memory takes a long (in terms of ms) time depending on the device architecture the modifications will only become. permanent when calling mvIMPACT::acquire::UserData::writeToHardware.

If data at the end of the list of entries doesn't fit in the memory it will be discarded and therefore will not be visible the next time the device is enumerated/accessed after the running process has terminated or the device has been disconnected.

Note
Entries that contain no data will not be stored in hardware. If e.g. 5 user data entries have been created, but only entry 0, 1, 2 and 4 contain data the write operation will pack the data in a way that when the user data is read from the device again (when the driver for that device is loaded the next time) the list of entries will contain elements at position 0, 1, 2 and 3 but NOT a index number 4. Deleting an entry from the middle of the list of user data however will NOT move all remaining entries one step towards the front of the list. Therefore during one session the entry indexes will NOT change. They can either become invalid (when the corresponding entry has been deleted), can get valid (newly created entries will always appear at the next free entry, thus deleting and entry and creating a new directly afterwards will create that entry at exactly the same index) or new entries can appear (when a new entry has been created and no free list position in the middle of the list of entries has been available).
The device must be closed in order to write the user data. Check the property mvIMPACT::acquire::Device::HWUpdateResult afterwards in order to make sure the data transfer was successful.
If a device does not offer user accessible data mvIMPACT::acquire::UserDataEntry objects will still be returned by certain functions. To check if this feature is available call mvIMPACT::acquire::UserData::isAvailable.
If the user accessible data currently can't be modified an exception of type mvIMPACT::acquire::ENoWriteRights will be thrown.
Instances of this class cannot be constructed directly. To get access the function mvIMPACT::acquire::Device::getUserData. must be used.

Member Function Documentation

◆ createEntry()

UserDataEntry createEntry ( void  )
inline

Creates and returns a new entry to store user specific data.

Note
The data handled by this object will not be stored permanently in the devices non-volatile memory until mvIMPACT::acquire::UserData::writeToHardware has been called successfully.
See also
mvIMPACT::acquire::UserData::deleteEntry,
mvIMPACT::acquire::UserData::writeToHardware
Returns
A new mvIMPACT::acquire::UserDataEntry instance that can be used to store user specific data in the devices non-volatile memory.

◆ deleteEntry()

void deleteEntry ( UserDataEntry userDataEntry)
inline

Deletes an entry of user specific data.

If the entry has been stored to the non-volatile memory already and has been assigned the mvIMPACT::acquire::udarPassword flag, this call will fail, when mvIMPACT::acquire::UserDataEntry::password does not contain the correct password.

Note
The data handled by this object will not be removed permanently from the devices non-volatile memory until mvIMPACT::acquire::UserData::writeToHardware( void ) const has been called successfully.
See also
mvIMPACT::acquire::UserData::createEntry,
mvIMPACT::acquire::UserData::writeToHardware
Parameters
[in]userDataEntryA reference to the entry to delete

◆ getFreeMemory()

int getFreeMemory ( void  ) const
inline

Returns the number of bytes of user accessible, non-volatile memory that is still available.

Since
1.12.64

◆ getUserDataEntry()

UserDataEntry getUserDataEntry ( int  nr) const
inline

Returns An object to work with an existing entry of user specific data.

Note
If an invalid number has been passed as nr an object will be returned as well. Therefore always check if the entry is valid by calling mvIMPACT::acquire::UserDataEntry::isValid before working with the object.
Returns
An object to work with an existing entry of user specific data.
Parameters
[in]nrThe number of the entry to return

◆ isAvailable()

bool isAvailable ( void  ) const
inline

This function should be called to check if this device offers non-volatile memory that can be accessed by the user.

Returns
  • true if the device offers non-volatile memory that can be accessed by the user
  • false otherwise

◆ validUserDataEntryIndexes()

void validUserDataEntryIndexes ( std::vector< int > &  sequence) const
inline

Fills an array with all currently valid user data entry indexes.

This function can be used to obtain a list of valid parameters for calls to the function mvIMPACT::acquire::UserData::getUserDataEntry. Every value in the returned array will (when passed to the function mvIMPACT::acquire::UserData::getUserDataEntry) result in a valid mvIMPACT::acquire::UserDataEntry object.

Parameters
[out]sequenceA reference to the array receiving the list of valid indexes

◆ writeToHardware()

void writeToHardware ( void  ) const
inline

Writes the current set of user data into the devices non-volatile memory.

This function might take a while. Depending on the device architecture and the amount of memory up to some hundred ms. Therefore make sure this function is not called more often than necessary to let your application perform efficiently.

See also
mvIMPACT::acquire::UserData::createEntry,
mvIMPACT::acquire::UserData::deleteEntry

Friends And Related Function Documentation

◆ Device

friend class Device
friend

Member Data Documentation

◆ memoryAvailable_bytes

PropertyI memoryAvailable_bytes

An integer property (read-only) containing the number of bytes of user accessible, non-volatile memory this device has available.

◆ memoryConsumed_bytes

PropertyI memoryConsumed_bytes

An integer property (read-only) containing the number of bytes of user accessible, non-volatile memory currently consumed by user data.

This doesn't indicate that all the data has already been stored in the non-volatile memory, but is the number of bytes needed to store the current user data permanently. No check for overflows will be performed. If the user defined data exceeds the size of the available memory, this data will be lost when disconnecting or switching of the supply voltage for this device.

To write data permanently into the device call the function mvIMPACT::acquire::UserData::writeToHardware But even after calling this function data that exceeds the available memory will be lost when the device looses supply voltage and/or the process terminates.

◆ reconnectBehaviour

An enumerated integer property that can be used to configure how the user data should be treated in case of a device that has been unplugged is plugged back in again.

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

If a device does not support hot-plugging, this property will be invisible (mvIMPACT::acquire::Component::isVisible()),


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