Impact Acquire SDK .NET
UserDataEntry Class Referencesealed

A helper class that represents one entry in the devices non-volatile memory (if available). More...

Public Attributes

readonly EnumPropertyI< TUserDataAccessRightaccess = new EnumPropertyI<TUserDataAccessRight>()
 The access rights for this entry.
 
readonly PropertyS data = new PropertyS()
 The data stored in this entry.
 
readonly PropertyS name = new PropertyS()
 The name of the entry.
 
readonly PropertyS password = new PropertyS()
 The password needed to modify this entry.
 

Properties

bool isValid [get]
 Call this function to check if this object references an existing entry.
 

Detailed Description

A helper class that represents one entry in the devices non-volatile memory (if available).

Each entry of user and device specific data consists of a name, data a property defining the access rights for this entry and an optional password.

The name can be any string, but currently is limited to 255 characters.

The mv.impact.acquire.UserDataEntry.data property can hold any type of user data that shall be stored in the device's non-volatile memory. This can either be a string or binary data. To store binary data the function mv.impact.acquire.PropertyS.writeBinary can be used. Internally however binary data will be stored as a Base64 encoded string. To read binary data from the property again the function mv.impact.acquire.PropertyS.readBinary must be called. The theoretical limit for the amount of data per entry is 2^16 (64KB) bytes, however the real limit might be below this value because the device does not offer that much memory.

The mv.impact.acquire.UserDataEntry.access property defines the access rights the user has when working with the entry. AFTER creation but BEFORE storing the entry into the device this property can be modified. At this point the creator of the entry can choose between 2 options: mv.impact.acquire.TUserDataAccessRight.udarFull and mv.impact.acquire.TUserDataAccessRight.udarRW. After storing the entry into the device by calling mv.impact.acquire.UserData.writeToHardware this property will become read-only and will remain read-only until the complete entry is deleted.

When the user creates a new entry for the user accessible device non-volatile memory he can either create a read/write data set, which means that every user can modify the data and the name property. In that case the property password is ignored. Apart from that an entry that can only be modified when the correct password has been written to the password property. To read a value is always allowed.

The password property will hold the user input and NOT the actual password needed to unlock the data set. However when an entry has been created the creator afterwards can write to the password. When the creator then calls the function mv.impact.acquire.UserData.writeToHardware the value of the password property is used as the 'real' password from that moment onwards.

The maximum length for the password currently is 255 characters. This does not provide total security of cause, but the idea of the password only is to hinder the user from deleting an import entry by accident.

The memory consumed by a single mv.impact.acquire.UserDataEntry can vary from device to device and depends on the way the data is stored internally. In any case when an entry is created it will consume more memory than the amount of bytes written to the mv.impact.acquire.UserDataEntry.data. After data has been written to an entry it is therefore important to check the mv.impact.acquire.UserData.memoryAvailable_bytes property if there is still enough memory available.

Note
There might be entries that can't be modified by the user. These entries contain important data that have been written to the memory during production. An attempt to delete this data will fail.

Example

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
{
UserData userData = pDev.userData;
if (!userData.isAvailable)
{
Console.WriteLine("This device does not support user data");
return -1;
}
Console.WriteLine("Available user memory(bytes): {0}", userData.memoryAvailable_bytes.read());
Console.WriteLine("Memory consumed already(bytes): {0}", userData.memoryConsumed_bytes.read());
// create a new entry
if (!entry.isValid)
{
Console.WriteLine("Failed to create new entry");
return -2;
}
entry.data.writeBinary(pData);
entry.name.write(entryName);
// write to non-volatile memory (therefore the device MUST be closed)
if (pDev.isOpen)
{
Console.WriteLine("Can't store data as the device is already in use");
return -3;
}
userData.writeToHardware();
if (pDev.HWUpdateResult.read() != THWUpdateResult.urSetUserDataWriteOK)
{
Console.WriteLine("Failed to store data in device non-volatile memory");
return -4;
}
// now this data is stored in the devices permanent memory
return 0;
}
bool isValid
Checks if the internal component referenced by this object is still valid.
Definition Component.cs:727
This class and its functions represent an actual device detected by this interface in the current sys...
Definition Device.cs:91
bool isOpen
Returns the current initialisation status in this process.
Definition Device.cs:430
readonly EnumPropertyI< THWUpdateResult > HWUpdateResult
An enumerated integer property (read-only) defining user executed hardware update results.
Definition Device.cs:737
A template class to represent 32 bit integer properties and 32 bit enumerated integer properties.
Definition EnumPropertyI.cs:61
EnumPropertyI< T > write(T value)
Writes one value to the property.
Definition EnumPropertyI.cs:449
T read()
Reads a value from a property.
Definition EnumPropertyI.cs:342
A helper class that represents one entry in the devices non-volatile memory (if available).
Definition UserDataEntry.cs:111
readonly PropertyS data
The data stored in this entry.
Definition UserDataEntry.cs:186
readonly PropertyS name
The name of the entry.
Definition UserDataEntry.cs:176
A helper class to work with the device specific non-volatile memory(if available).
Definition UserData.cs:59
bool isAvailable
This function should be called to check if this device offers non-volatile memory that can be accesse...
Definition UserData.cs:304
readonly PropertyI memoryConsumed_bytes
An integer property (read-only) containing the number of bytes of user accessible,...
Definition UserData.cs:356
readonly PropertyI memoryAvailable_bytes
An integer property (read-only) containing the number of bytes of user accessible,...
Definition UserData.cs:344
void writeToHardware()
Writes the current set of user data into the devices non-volatile memory.
Definition UserData.cs:263
UserDataEntry createEntry()
Creates and returns a new entry to store user specific data.
Definition UserData.cs:194
Note
Instances of this class can only be created by the class UserData.

Member Data Documentation

◆ access

The access rights for this entry.

After this entry has been written to the devices non-volatile memory, this property will become read-only.

Valid values for this property are defined by the enumeration mv.impact.acquire.TUserDataAccessRight.

◆ data

The data stored in this entry.

The theoretical limit for the amount of data per entry is 2^16 (64KB) bytes, however the real limit might be below this value because the device does not offer that much memory.

This property can either store string or binary data. See mv.impact.acquire.PropertyS to find out how to work with binary data.

◆ name

The name of the entry.

The maximum length for the name currently is 255 characters.

◆ password

The password needed to modify this entry.

The maximum length for the password is 255 characters currently. When the mv.impact.acquire.TUserDataAccessRight.udarPassword is not specified by the access property, this property will be ignored. Otherwise this property must have been assigned the correct password (case sensitive) before the name and data properties can be modified.

Property Documentation

◆ isValid

bool isValid
get

Call this function to check if this object references an existing entry.

Returns
  • true if this object references an existing entry
  • false otherwise