Impact Acquire SDK Java
UserData Class Reference

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

Public Member Functions

UserDataEntry createEntry ()
 Creates and returns a new entry to store user specific data.
 
synchronized void delete ()
 
void deleteEntry (UserDataEntry userDataEntry)
 Deletes an entry of user specific data.
 
int getFreeMemory ()
 Returns the number of bytes of user accessible, non-volatile memory that is still available.
 
PropertyI getMemoryAvailable_bytes ()
 An integer property (read-only) containing the number of bytes of user accessible, non-volatile memory this device has available.
 
PropertyI getMemoryConsumed_bytes ()
 An integer property (read-only) containing the number of bytes of user accessible, non-volatile memory currently consumed by user data.
 
PropertyI getReconnectBehaviour ()
 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.
 
UserDataEntry getUserDataEntry (int nr)
 Returns An object to work with an existing entry of user specific data.
 
boolean isAvailable ()
 This function should be called to check if this device offers non-volatile memory that can be accessed by the user.
 
void validUserDataEntryIndexes (IntVector sequence)
 Fills an array with all currently valid user data entry indexes.
 
void writeToHardware ()
 Writes the current set of user data into the devices non-volatile memory.
 

Protected Member Functions

void finalize ()
 
 UserData (long cPtr, boolean cMemoryOwn)
 

Static Protected Member Functions

static long swigRelease (UserData obj)
 

Protected Attributes

transient boolean swigCMemOwn
 

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.getHWUpdateResult() 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.

Constructor & Destructor Documentation

◆ UserData()

UserData ( long cPtr,
boolean cMemoryOwn )
protected

Member Function Documentation

◆ createEntry()

UserDataEntry createEntry ( )

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.

◆ delete()

synchronized void delete ( )

◆ deleteEntry()

void deleteEntry ( UserDataEntry userDataEntry)

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.TUserDataAccessRight.udarPassword flag, this call will fail, when mvIMPACT.acquire.UserDataEntry.getPassword() 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
userDataEntry[in] A reference to the entry to delete

◆ finalize()

void finalize ( )
protected

◆ getFreeMemory()

int getFreeMemory ( )

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

Since
1.12.64

◆ getMemoryAvailable_bytes()

PropertyI getMemoryAvailable_bytes ( )

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

◆ getMemoryConsumed_bytes()

PropertyI getMemoryConsumed_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.

◆ getReconnectBehaviour()

PropertyI getReconnectBehaviour ( )

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()),

◆ getUserDataEntry()

UserDataEntry getUserDataEntry ( int nr)

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
nr[in] The number of the entry to return

◆ isAvailable()

boolean isAvailable ( )

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

◆ swigRelease()

static long swigRelease ( UserData obj)
staticprotected

◆ validUserDataEntryIndexes()

void validUserDataEntryIndexes ( IntVector sequence)

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
sequence[out] A reference to the array receiving the list of valid indexes

◆ writeToHardware()

void writeToHardware ( void )

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

Member Data Documentation

◆ swigCMemOwn

transient boolean swigCMemOwn
protected