mpiMapPtrToString
Declaration
MPI_DECL1 MPI_RESULT MPI_DECL2 mpiMapPtrToString(MPIMap mpiMap, const MPIMapPtr *info, char *buffer, size_t bufferSize, size_t* reqiredBufferSize);
Required Header: map.h
Change History: Added in 04.00.
Description
mpiMapPtrToString translates an MPIMapPtr structure into a string. This is useful when saving configuration information to a file.
First mpiMapPtrToString attempts to convert the data in MPIMapPtr to a MPIMapSymbol structure. If successful, the string follows the form of:
MPIMapSymbolType<enumeration value>[index 0][index 1][index 2]
where only enough indices are used to specify the controller memory location. Specific examples:
MPIMapSymbolTypeSAMPLE_COUNTER MPIMapSymbolTypeCONTROL_DIGITAL_IN[0] MPIMapSymbolTypeSQNODE_DIGITAL_OUT[0][3][1]
If mpiMapPtrToString is unable to translate the MPIMapPtr structure to an MPIMapSymbol structure, then mpiMapPtrToString attempts to represent the controller memory location as a VM3 string with an optional mask:
<VM3 string>|mask=<mask>
Specific examples:
MFWData.SystemData.Signature MFWData.SystemData.Signature|mask=0xFFFF0000
If translation to a VM3 string fails, then mpiMapPtrToString will convert the host address in MPIMapPtr to a firmware address and represent the information as follows:
addr=<firmware address>|mask=<mask>
Specific examples:
addr=0x10001234 addr=0x10005678|mask=0xFFFF
If the user specified buffer is not large enough to hold the string, then MPIMapMessageBUFFER_TOO_SMALL is returned and the required buffer size will be written to the variable pointed to by requiredBufferSize if requiredBufferSize is not NULL.
| mpiMap | The MPIMap object used to translate addresses. |
|---|---|
| info | A read-only pointer to the MPIMapPtr structure holding the mask and pointer to the controller memory which is to be converted to a string. |
| buffer | A pointer to a character array where the address string will be written. |
| bufferSize | The size of the user specified buffer. |
| requiredBufferSize | A pointer to the variable where the required buffer size for holding the converted string will be written. This value will be 1 plus the length of the string in order to make room for the null terminator. |
| Return Values |
|---|
| MPIMapMessageMAP_INVALID |
| MPIMessageARG_INVALID |
| MPIMapMessageVERSION_DEPENDENT_STRING |
| MPIMapMessageBUFFER_TOO_SMALL |
Sample Code
MPIMap mpiMap; MFWData *firmware; MPIMapPtr info; char buffer[500]; MPI_RESULT returnValue;
/* ... */
/* Obtain information about firmware->SystemData.SampleCounter assuming a mask of 0xFFFFFFFF*/ info.ptr.ul = &firmware->SystemData.SampleCounter; info.mask.ul = 0xFFFFFFFF;
returnValue = mpiMapPtrToString(mpiMap, &info, buffer, sizeof(buffer), NULL);
/* buffer should now hold the string "MPIMapSymbolTypeSAMPLE_COUNTER" */
See Also