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.
void	deleteEntry (UserDataEntry userDataEntry)
	Deletes an entry of user specific data.
UserDataEntry	getUserDataEntry (int nr)
	Returns An object to work with an existing entry of user specific data.
void	writeToHardware ()
	Writes the current set of user data into the devices non-volatile memory.

Public Attributes
readonly PropertyI	memoryAvailable_bytes = new PropertyI()
	An integer property (read-only) containing the number of bytes of user accessible, non-volatile memory this device has available.
readonly PropertyI	memoryConsumed_bytes = new PropertyI()
	An integer property (read-only) containing the number of bytes of user accessible, non-volatile memory currently consumed by user data.
readonly EnumPropertyI< TUserDataReconnectBehaviour >	reconnectBehaviour = new EnumPropertyI<TUserDataReconnectBehaviour>()
	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.

Properties
int	freeMemory [get]
	Returns the number of bytes of user accessible, non-volatile memory that is still available.
bool	isAvailable [get]
	This function should be called to check if this device offers non-volatile memory that can be accessed by the user.
IEnumerable< UserDataEntry >	userDataEntries [get]
	Returns a new enumerator for instances of the class mv.impact.acquire.UserDataEntry.
List< int >	validUserDataEntryIndexes [get]
	Fills an array with all currently valid user data entry indexes.

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 mv.impact.acquire.UserDataEntry as well as creating a new entry by calling mv.impact.acquire.UserData.createEntry or deleting an entry with the function mv.impact.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 mv.impact.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 mv.impact.acquire.Device.HWUpdateResult afterwards in order to make sure the data transfer was successful.

If a device does not offer user accessible data mv.impact.acquire.UserDataEntry objects will still be returned by certain functions. To check if this feature is available call mv.impact.acquire.UserData.isAvailable.

If the user accessible data currently can't be modified an exception of type mv.impact.acquire.ENoWriteRights will be thrown.

Instances of this class cannot be constructed directly. To get access the function mv.impact.acquire.Device.userData. must be used.

Member Function Documentation

createEntry()

UserDataEntry createEntry ( )

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 mv.impact.acquire.UserData.writeToHardware has been called successfully.

See also

mv.impact.acquire.UserData.deleteEntry,
mv.impact.acquire.UserData.writeToHardware

Returns

A new mv.impact.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 mv.impact.acquire.TUserDataAccessRight.udarPassword flag, this call will fail, when mv.impact.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 mv.impact.acquire.UserData.writeToHardware( void ) const has been called successfully.

See also

mv.impact.acquire.UserData.createEntry,
mv.impact.acquire.UserData.writeToHardware

Parameters

[in]

userDataEntry

A reference to the entry to delete

getUserDataEntry()

UserDataEntry getUserDataEntry ( int nr )

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 mv.impact.acquire.UserDataEntry.isValid before working with the object.

Returns

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

Parameters

[in]

nr

The number of the entry to return

writeToHardware()

void writeToHardware ( void )

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

mv.impact.acquire.UserData.createEntry,
mv.impact.acquire.UserData.deleteEntry

Member Data Documentation

memoryAvailable_bytes

readonly PropertyI memoryAvailable_bytes = new PropertyI()

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

memoryConsumed_bytes

readonly PropertyI memoryConsumed_bytes = new PropertyI()

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 mv.impact.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

readonly EnumPropertyI<TUserDataReconnectBehaviour> reconnectBehaviour = new EnumPropertyI<TUserDataReconnectBehaviour>()

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 mv.impact.acquire.TUserDataReconnectBehaviour.

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

Property Documentation

freeMemory

int freeMemory

get

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

Since

1.12.64

isAvailable

bool isAvailable

get

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

userDataEntries

IEnumerable<UserDataEntry> userDataEntries

get

Returns a new enumerator for instances of the class mv.impact.acquire.UserDataEntry.

validUserDataEntryIndexes

List<int> validUserDataEntryIndexes

get

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 mv.impact.acquire.UserData.getUserDataEntry. Every value in the returned array will (when passed to the function mv.impact.acquire.UserData.getUserDataEntry) result in a valid mv.impact.acquire.UserDataEntry object.