Class UserMemory

Defined in File UserMemoryApi.h

Class Documentation

class UserMemory

This class contains user memory functions.

Public Functions

UserMemory(WMX3Api *f): Constructor to initialize an object of this class. The device created by the WMX3Api object passed to this constructor is used to execute API functions. Also see Devices.

UserMemory(const UserMemory &src): Copy constructor to initialize an object of this class based on an existing object of this class. Also see Copy Operators.

UserMemory &operator=(const UserMemory &src): Copy assignment operator to initialize an object of this class based on an existing object of this class. Also see Copy Operators.

UserMemory(): Constructor to initialize an object of this class with a self device. Also see Self Devices.

~UserMemory(): Destructor for this class.

bool IsDeviceValid()

Return TRUE if this class object has access to a device, and FALSE otherwise. A device is required to execute most functions in this class. If this function returns FALSE, a device can be created by calling the CreateDevice function from the WMX3Api object that was passed to the constructor of this class.

WMX3APIFUNC GetVersion(int *pMajorVersion, int *pMinorVersion, int *pRevisionVersion, int *pFixVersion)

Get the version of the module rtdll.

Parameters:

pMajorVersion – [out] The major version number.
pMinorVersion – [out] The minor version number.
pRevisionVersion – [out] The revision version number.
pFixVersion – [out] The fix version number.

WMX3APIFUNC SetMBit(unsigned int addr, unsigned int bit, unsigned char data)

Set the value of a user memory bit.

Parameters:

addr – [in] The byte address of the bit to set.
bit – [in] The bit address of the bit to set.
data – [in] The value to set the bit to.

WMX3APIFUNC SetMByte(unsigned int addr, unsigned char data)

Set the value of a user memory byte.

Parameters:

addr – [in] The address of the byte to set.
data – [in] The value to set the byte to.

WMX3APIFUNC SetMBytes(unsigned int addr, unsigned int size, unsigned char *pData)

Set the value of multiple user memory bytes.

The maximum number of bytes that this function can write per function call is maxUserMemoryReadWriteBytes. If this size is exceeded, an error will be returned. To write a greater range of the user memory space, call this function multiple times.

Remark

This function does not set the specified data atomically. If the data is read by another thread at the same time, partially updated data may be read.

Parameters:

addr – [in] The byte address of the head byte.
size – [in] The number of bytes to set.
pData – [in] A pointer to an unsigned char array that contains the values to set the bytes to. The size of the array must be greater than or equal to the size parameter.

WMX3APIFUNC SetMBits(unsigned int *pAddr, unsigned int *pBit, unsigned char *pData, unsigned int count)

Set the value of multiple user memory bits.

This function is equivalent to calling the SetMBit function multiple times, but can be faster due to the reduced overhead. There is no limit to the number of bits that may be specified at once. pAddr[0], pBit[0], and pData[0] specify the first memory bit to set, pAddr[1], pBit[1], and pData[1] specify the second memory bit to set, and so on. The bits can be specified in any order.

Remark

The difference between the largest byte address and the smallest byte address specified to this function must be less than half of maxUserMemoryReadWriteBytes. If the difference exceeds this limit, an error will be returned.

Parameters:

pAddr – [in] A pointer to an int array that contains the byte addresses of the user memory bits. The size of the array must be equal to the count parameter.
pBit – [in] A pointer to an int array that contains the bit addresses of the user memory bits. The size of the array must be equal to the count parameter.
pData – [in] A pointer to an unsigned char array that contains the values to set the bits to. The size of the array must be equal to the count parameter.
count – [in] The number of bits to set.

WMX3APIFUNC SetMAnalogDataChar(int addr, char analogData)

Set the value of user memory analog data spanning one byte.

This function sets one byte of the user memory address space to the specified char type analog data value.

Remark

Parameters:

addr – [in] The byte address of the first byte of the user memory data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC SetMAnalogDataUChar(int addr, unsigned char analogData)

Set the value of user memory analog data spanning one byte.

This function sets one byte of the user memory address space to the specified unsigned char type analog data value. of the user memory.

Remark

Parameters:

addr – [in] The byte address of the first byte of the user memory data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC SetMAnalogDataShort(int addr, short analogData)

Set the value of user memory analog data spanning two bytes.

This function sets two bytes of the user memory address space to the specified short type analog data value. user memory.

Remark

If the address of the data set by this function crosses the boundary of a multiple of 64 (addr is 63, 127, 191, 255, etc.), the data is not set atomically. In this case, if the data is read by another thread at the same time, partially updated data may be read.

Parameters:

addr – [in] The byte address of the first byte of the user memory data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC SetMAnalogDataUShort(int addr, unsigned short analogData)

Set the value of user memory analog data spanning two bytes.

This function sets two bytes of the user memory address space to the specified unsigned short type analog data value. of the user memory.

Remark

If the address of the data set by this function crosses the boundary of a multiple of 64 (addr is 63, 127, 191, 255, etc.), the data is not set atomically. In this case, if the data is read by another thread at the same time, partially updated data may be read.

Parameters:

addr – [in] The byte address of the first byte of the user memory data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC SetMAnalogDataInt(int addr, int analogData)

Set the value of user memory analog data spanning four bytes.

This function sets four bytes of the user memory address space to the specified int type analog data value. user memory.

Remark

If the address of the data set by this function crosses the boundary of a multiple of 64 (addr is 61-63, 125-127, 189-191, 253-255, etc.), the data is not set atomically. In this case, if the data is read by another thread at the same time, partially updated data may be read.

Parameters:

addr – [in] The byte address of the first byte of the user memory data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC SetMAnalogDataUInt(int addr, unsigned int analogData)

Set the value of user memory analog data spanning four bytes.

This function sets four bytes of the user memory address space to the specified unsigned int type analog data value. of the user memory.

Remark

If the address of the data set by this function crosses the boundary of a multiple of 64 (addr is 61-63, 125-127, 189-191, 253-255, etc.), the data is not set atomically. In this case, if the data is read by another thread at the same time, partially updated data may be read.

Parameters:

addr – [in] The byte address of the first byte of the user memory data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC GetMBit(unsigned int addr, unsigned int bit, unsigned char *pData)

Get the value of a user memory bit.

Parameters:

addr – [in] The byte address of the bit to get.
bit – [in] The bit address of the bit to get.
pData – [out] A pointer to a unsigned char that will receive the data.

WMX3APIFUNC GetMByte(unsigned int addr, unsigned char *pData)

Get the value of a user memory byte.

Parameters:

addr – [in] The address of the byte to get.
pData – [out] A pointer to a unsigned char that will receive the data.

WMX3APIFUNC GetMBytes(unsigned int addr, unsigned int size, unsigned char *pData)

Get the value of multiple user memory bytes.

The maximum number of bytes that this function can read per function call is maxUserMemoryReadWriteBytes. If this size is exceeded, an error will be returned. To read a greater range of the user memory space, call this function multiple times.

Remark

This function does not read the specified data atomically. If the data is overwritten by another thread at the same time, partially updated data may be read.

Parameters:

addr – [in] The byte address of the head byte.
size – [in] The number of bytes to get.
pData – [out] A pointer to a unsigned char array that will receive the data. The size of the array must be greater than or equal to the size parameter.

WMX3APIFUNC GetMAnalogDataChar(unsigned int addr, char *pAnalogData)

Get the value of user memory analog data spanning one byte.

This function reads one byte of the user memory address space and returns the data as a char type analog data value.

Remark

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetMAnalogDataUChar(unsigned int addr, unsigned char *pAnalogData)

Get the value of user memory analog data spanning one byte.

This function reads one byte of the user memory address space and returns the data as an unsigned char type analog data value.

Remark

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetMAnalogDataShort(unsigned int addr, short *pAnalogData)

Get the value of user memory analog data spanning two bytes.

This function reads two bytes of the user memory address space and returns the data as a short type analog data value.

Remark

If the address of the data read by this function crosses the boundary of a multiple of 64 (addr is 63, 127, 191, 255, etc.), the data is not read atomically. In this case, if the data is overwritten by another thread at the same time, partially updated data may be read.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetMAnalogDataUShort(unsigned int addr, unsigned short *pAnalogData)

Get the value of user memory analog data spanning two bytes.

This function reads two bytes of the user memory address space and returns the data as an unsigned short type analog data value.

Remark

If the address of the data read by this function crosses the boundary of a multiple of 64 (addr is 63, 127, 191, 255, etc.), the data is not read atomically. In this case, if the data is overwritten by another thread at the same time, partially updated data may be read.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetMAnalogDataInt(unsigned int addr, int *pAnalogData)

Get the value of user memory analog data spanning four bytes.

This function reads four bytes of the user memory address space and returns the data as an int type analog data value.

Remark

If the address of the data read by this function crosses the boundary of a multiple of 64 (addr is 61-63, 125-127, 189-191, 253-255, etc.), the data is not read atomically. In this case, if the data is overwritten by another thread at the same time, partially updated data may be read.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetMAnalogDataUInt(unsigned int addr, unsigned int *pAnalogData)

Get the value of user memory analog data spanning four bytes.

This function reads four bytes of the user memory address space and returns the data as an unsigned int type analog data value.

Remark

If the address of the data read by this function crosses the boundary of a multiple of 64 (addr is 61-63, 125-127, 189-191, 253-255, etc.), the data is not read atomically. In this case, if the data is overwritten by another thread at the same time, partially updated data may be read.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC SetMBitEx(unsigned int addr, unsigned int bit, unsigned char data)

Set the value of a user memory bit.

This function has a faster response time compared to SetMBit.

Remark

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the bit to set.
bit – [in] The bit address of the bit to set.
data – [in] The value to set the bit to.

WMX3APIFUNC SetMByteEx(unsigned int addr, unsigned char data)

Set the value of a user memory byte.

This function has a faster response time compared to SetMByte.

Remark

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The address of the byte to set.
data – [in] The value to set the byte to.

WMX3APIFUNC SetMBytesEx(unsigned int addr, unsigned int size, unsigned char *pData)

Set the value of multiple user memory bytes.

This function has a faster response time compared to SetMBytes.

Remark

Unlike the SetMBytes function, the size of the written data can be greater than maxUserMemoryReadWriteBytes.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the head byte.
size – [in] The number of bytes to set.
pData – [in] A pointer to a unsigned char array that contains the values to set the bytes to. The size of the array must be greater than or equal to the size parameter.

WMX3APIFUNC SetMBitsEx(unsigned int *pAddr, unsigned int *pBit, unsigned char *pData, unsigned int count)

Set the value of multiple user memory bits.

This function is equivalent to calling the SetMBit function multiple times, but can be faster due to the reduced overhead. There is no limit to the number of bits that may be specified at once. pAddr[0], pBit[0], and pData[0] specify the first user memory bit to set, pAddr[1], pBit[1], and pData[1] specify the second user memory bit to set, and so on. The bits can be specified in any order.

Remark

This function has a faster response time compared to SetMBits.

Unlike the SetMBits function, the difference between the largest byte address and the smallest byte address can be equal to or larger than half of maxUserMemoryReadWriteBytes.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

pAddr – [in] A pointer to an int array that contains the byte addresses of the user memory bits. The size of the array must be equal to the count parameter.
pBit – [in] A pointer to an int array that contains the bit addresses of the user memory bits. The size of the array must be equal to the count parameter.
pData – [in] A pointer to an unsigned char array that contains the values to set the bits to. The size of the array must be equal to the count parameter.
count – [in] The number of bits to set.

WMX3APIFUNC SetMAnalogDataCharEx(int addr, char analogData)

Set the value of user memory analog data spanning one byte.

This function sets one byte of the user memory address space to the specified char type analog data value.

Remark

This function has a faster response time compared to SetMAnalogDataChar.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC SetMAnalogDataUCharEx(int addr, unsigned char analogData)

Set the value of user memory analog data spanning one byte.

This function sets one byte of the user memory address space to the specified unsigned char type analog data value.

Remark

This function has a faster response time compared to SetMAnalogDataUChar.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC SetMAnalogDataShortEx(int addr, short analogData)

Set the value of user memory analog data spanning two bytes.

This function sets two bytes of the user memory address space to the specified short type analog data value.

Remark

This function has a faster response time compared to SetMAnalogDataShort.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC SetMAnalogDataUShortEx(int addr, unsigned short analogData)

Set the value of user memory analog data spanning two bytes.

This function sets two bytes of the user memory address space to the specified unsigned short type analog data value.

Remark

This function has a faster response time compared to SetMAnalogDataUShort.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC SetMAnalogDataIntEx(int addr, int analogData)

Set the value of user memory analog data spanning four bytes.

This function sets four bytes of the user memory address space to the specified int type analog data value.

Remark

This function has a faster response time compared to SetMAnalogDataInt.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC SetMAnalogDataUIntEx(int addr, unsigned int analogData)

Set the value of user memory analog data spanning four bytes.

This function sets four bytes of the user memory address space to the specified unsigned int type analog data value.

Remark

This function has a faster response time compared to SetMAnalogDataUInt.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
analogData – [in] The value of the analog data to set the user memory bytes to.

WMX3APIFUNC GetMBitEx(unsigned int addr, unsigned int bit, unsigned char *pData)

Get the value of a user memory bit.

This function has a faster response time compared to GetMBit.

Remark

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the bit to get.
bit – [in] The bit address of the bit to get.
pData – [out] A pointer to a unsigned char that will receive the data.

WMX3APIFUNC GetMByteEx(unsigned int addr, unsigned char *pData)

Get the value of a user memory byte.

This function has a faster response time compared to GetMByte.

Remark

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The address of the byte to get.
pData – [out] A pointer to a unsigned char that will receive the data.

WMX3APIFUNC GetMBytesEx(unsigned int addr, unsigned int size, unsigned char *pData)

Get the value of multiple user memory bytes.

This function has a faster response time compared to GetMBytes.

Remark

Unlike the GetMBytes function, the size of the read data can be greater than maxUserMemoryReadWriteBytes.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the head byte.
size – [in] The number of bytes to get.
pData – [out] A pointer to a unsigned char array that will receive the data. The size of the array must be greater than or equal to the size parameter.

WMX3APIFUNC GetMAnalogDataCharEx(unsigned int addr, char *pAnalogData)

Get the value of user memory analog data spanning one byte.

This function reads one byte of the user memory address space and returns the data as a char type analog data value.

Remark

This function has a faster response time compared to GetMAnalogDataChar.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetMAnalogDataUCharEx(unsigned int addr, unsigned char *pAnalogData)

Get the value of user memory analog data spanning one byte.

This function reads one byte of the user memory address space and returns the data as an unsigned char type analog data value.

Remark

This function has a faster response time compared to GetMAnalogDataUChar.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetMAnalogDataShortEx(unsigned int addr, short *pAnalogData)

Get the value of user memory analog data spanning two bytes.

This function reads two bytes of the user memory address space and returns the data as a short type analog data value.

Remark

This function has a faster response time compared to GetMAnalogDataShort.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetMAnalogDataUShortEx(unsigned int addr, unsigned short *pAnalogData)

Get the value of user memory analog data spanning two bytes.

This function reads two bytes of the user memory address space and returns the data as an unsigned short type analog data value.

Remark

This function has a faster response time compared to GetMAnalogDataUShort.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetMAnalogDataIntEx(unsigned int addr, int *pAnalogData)

Get the value of user memory analog data spanning four bytes.

This function reads four bytes of the user memory address space and returns the data as an int type analog data value.

Remark

This function has a faster response time compared to GetMAnalogDataInt.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetMAnalogDataUIntEx(unsigned int addr, unsigned int *pAnalogData)

Get the value of user memory analog data spanning four bytes.

This function reads four bytes of the user memory address space and returns the data as an unsigned int type analog data value.

Remark

This function has a faster response time compared to GetMAnalogDataUInt.

Because of the difference in the data flow channel, this function cannot be called from an ApiBuffer.

Parameters:

addr – [in] The byte address of the first byte of the analog data.
pAnalogData – [out] A pointer to a char that will receive the data.

WMX3APIFUNC GetUserMemoryAddress(void **pptr)

Get a pointer to the memory address of the user memory address space.

This function returns a pointer to the user memory address space. This allows direct access of the user memory.

Remark

This function will return an error if a valid pointer to the user memory address space cannot be obtained.

The pointer to the user memory address space will become invalid after the UserMemory object that calls this function is destroyed. Using the pointer after this function is destroyed could cause a system error.

This function is not supported in the .NET CLR library.

Parameters:: pptr – [out] A pointer to a pointer that will be return the memory address of the user memory address space.

Public Static Functions

static WMX3APIFUNC ErrorToString(int errCode, char *pString, unsigned int size)

Get a string representation of the specified error code.

This function returns a string representation of the specified error code. The error code must be defined in the UserMemoryErrorCode enum or the ErrorCode enum in the WMX3Api.h header. All errors returned by functions in class UserMemory will be defined in one of these enums. Errors returned by functions in other classes may not be defined in one of these enums, and when such errors are passed to this function, an ErrorCodeNotDefined error will be returned and pString will contain the string representation of this error.

Remark

If pString is too small to contain the entire string representation of the error code, pString will be set to an empty string. An array size of 256 characters will be enough to hold all string representations.

This function is static, and may be called without declaring an instance of the UserMemory class or creating a device.

Parameters:

errCode – [in] The error code to get the string representation of.
pString – [in] A char array that will contain the string representation of the error.
size – [in] The size of the char array in number of characters.

static WMX3APIFUNC ErrorToString(int errCode, wchar_t *pString, unsigned int size)

Get a string representation of the specified error code.

This function is a variation of ErrorToString that accepts a wchar_t array. Use this function when using Unicode character sets.

Remark

Parameters:

errCode – [in] The error code to get the string representation of.
pString – [in] A wchar_t array that will contain the string representation of the error.
size – [in] The size of the wchar_t array in number of characters.

static WMX3APIFUNC ApiLogToString(unsigned char *pLogData, unsigned int logDataSize, char *pString, unsigned int size)

Get a string representation of the raw data of an API log.

This function converts the raw data for one API function call that was extracted from the API log with the GetApiLogData function.

Remark