UserData Class Reference

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

Inheritance diagram for UserData:

Public Member Functions
	__init__ (self, *args, **kwargs)
	createEntry (self)
	Creates and returns a new entry to store user specific data.
	deleteEntry (self, userDataEntry)
	Deletes an entry of user specific data.
	getFreeMemory (self)
	Returns the number of bytes of user accessible, non-volatile memory that is still available.
	getIsAvailable (self)
	This function should be called to check if this device offers non-volatile memory that can be accessed by the user.
	getUserDataEntry (self, nr)
	Returns An object to work with an existing entry of user specific data.
	validUserDataEntryIndexes (self, sequence)
	Fills an array with all currently valid user data entry indexes.
	writeToHardware (self)
	Writes the current set of user data into the devices non-volatile memory.

Properties
	isAvailable = property (getIsAvailable, None, None, None)
	A bool property (read-only) which checks if this device offers non-volatile memory that can be accessed by the user.
	memoryAvailable_bytes = property(lib_mvIMPACT_acquire.UserData_memoryAvailable_bytes_get, doc=)
	An integer property (read-only) containing the number of bytes of user accessible, non-volatile memory this device has available.
	memoryConsumed_bytes = property(lib_mvIMPACT_acquire.UserData_memoryConsumed_bytes_get, doc=)
	An integer property (read-only) containing the number of bytes of user accessible, non-volatile memory currently consumed by user data.
	reconnectBehaviour = property(lib_mvIMPACT_acquire.UserData_reconnectBehaviour_get, doc=)
	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.
	thisown = property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc="The membership flag")

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.

Constructor & Destructor Documentation

__init__()

__init__	(		self,
		*	args,
		**	kwargs )

Member Function Documentation

createEntry()

createEntry

(

self

)

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

deleteEntry	(		self,
			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.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

userDataEntry

[in] A reference to the entry to delete

getFreeMemory()

getFreeMemory

(

self

)

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

Since

1.12.64

getIsAvailable()

getIsAvailable

(

self

)

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

getUserDataEntry()

getUserDataEntry	(		self,
			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

validUserDataEntryIndexes()

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

writeToHardware

(

self

)

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

Property Documentation

isAvailable

isAvailable = property (getIsAvailable, None, None, None)

static

A bool property (read-only) which checks if this device offers non-volatile memory that can be accessed by the user.

See mvIMPACT.acquire.UserData.getIsAvailable()

memoryAvailable_bytes

memoryAvailable_bytes = property(lib_mvIMPACT_acquire.UserData_memoryAvailable_bytes_get, doc=)

static

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

memoryConsumed_bytes

memoryConsumed_bytes = property(lib_mvIMPACT_acquire.UserData_memoryConsumed_bytes_get, doc=)

static

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

reconnectBehaviour = property(lib_mvIMPACT_acquire.UserData_reconnectBehaviour_get, doc=)

static

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 may be: mvIMPACT.acquire.udrbKeepCachedData, mvIMPACT.acquire.udrbUpdateFromDeviceData.

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

thisown

thisown = property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc="The membership flag")

static