ProMapper API

This chapter describes API used to develop a ProMapper module by using ProFrame.

1. Overview

ProMapper provides the following general and variable-length array APIs.

  • General API

    The following describes each API related to input/output conversion.

    Function Description

    pfmMapperDuplicateStruct

    Copies a structure that is created by unmarshalling.

    pfmMapperNewStruct

    Newly creates memory space for a structure.

    pfmMapperFreeStruct

    Releases memory of a structure that is created by unmarshalling.

    pfmMapperFreeStructNoAlloc

    Releases memory of a structure created with pfmMapperUnmarshalNoAlloc.

    pfmMapperFreeMessage

    Releases memory of a message that is created by marshalling.

    pfmMapperUnmarshal

    Converts messages to structures.

    pfmMapperUnmarshalNoAlloc

    Converts messages to structures but does not allocate memory.

    pfmMapperMarshal

    Converts structures to messages.

    pfmMapperMarshalNoAlloc

    Converts structures to messages but does not allocate memory.

    pfmMapperConv

    Converts developer-defined resources according to mapping rules.

    pfmMapperGetError

    Gets an error message as a string if a function returns a value that is not MAPPER_RETURN_OK.

    pfmMapperSizeStruct

    Gets the structure size.

    pfmMapperSizeMessage

    Gets the message size.

  • Variable-length array API

    ProMapper provides a special structure to use variable-length arrays. Developers can develop applications without worrying about allocated memory management by using the structure.

    pfmVarray.h is declared in a header file of a structure that is automatically created in ProMapper. By using variable-length array API, each array’s index can be accessed.

    The following describes each variable-length array API.

    Function Description

    pfmVarrayAlloc

    Allocates a variable-length array with a specified size.

    pfmVarrayData

    Gets the pointer to a variable-length array.

    pfmVarrayAppend

    Appends data to the end of a variable-length array.

    pfmVarrayGet

    Passes the pointer to an element of a specific index in a variable-length array.

    pfmVarrayElementAt

    Passes the pointer to an element of a specific index in a variable-length array.

    pfmVarrayClearCount

    Initializes the number of elements in a variable-length array to 0.

    pfmVarrayCount

    Gets the number of elements in a variable-length array.

    pfmVarrayFree

    Releases a buffer in a variable-length array and initializes the array.

    pfmVarrayBufferSize

    Gets the memory size allocated to a variable-length array.

    pfmVarrayStructSize

    Gets the structure size of a variable-length array.

    pfmVarraySize

    Gets the size of a variable-length array.

2. General API

pfmMapperDuplicateStruct

Copies a structure that is created by unmarshalling. If a variable-length array exists in the structure, allocate separate memory and then copy the structure.

  • Prototype

    long pfmMapperDuplicateStruct(char *structName, char *sourceStructPtr,
char **targetStructPtr)

  • Parameters

    Parameter Description

    structName

    Name of a structure to copy.

    The name must be a name used when registering ProMapper. The name is case-sensitive and must be the same as that registered in Studio.

    sourceStructPtr

    Pointer to a structure to copy.

    targetStructPtr

    Reference value of a structure pointer to which memory is allocated after copying a structure.

  • Return values

    If there is no issue in copying a structure, the MAPPER_RETURN_OK code is returned. If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    Teststr1 *teststr1;
Teststr1 *teststr1_copy;
…
rc = pfmMapperDuplicateStruct(“Teststr1”, teststr1, & teststr1_copy);

  • Related functions

    pfmMapperFreeStruct

pfmMapperNewStruct

Newly creates memory space for a structure. The created memory is initialized as 0x00.

  • Prototype

    long pfmMapperNewStruct(char *structName, char **targetStructPtr)

  • Parameters

    Parameter Description

    structName

    Name of a structure to copy.

    The name must be a name used when registering ProMapper. The name is case-sensitive and must be the same as that registered in Studio.

    targetStructPtr

    Reference value of a structure pointer to which memory is allocated.

  • Return values

    Return Value Description

    MAPPER_RETURN_OK

    Success

    If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    Teststr1 *teststr1;
Teststr1 *teststr1_copy;
…
rc = pfmMapperNewStruct (“Teststr1”, & teststr1_copy);

  • Related functions

    pfmMapperDuplicateStruct

pfmMapperFreeStruct

Releases memory of a structure that is created by unmarshalling.

  • Prototype

    long pfmMapperFreeStruct(char *structName, char *structPtr)

  • Parameters

    Parameter Description

    structName

    Name of a structure for which memory is released.

    The name must be a name used when registering ProMapper. The name is case-sensitive and must be the same as that registered in Studio.

    structPtr

    Pointer to a structure for which memory is released.

  • Return values

    Return Value Description

    MAPPER_RETURN_OK

    Success

    If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    Teststr1 *teststr1;
…
rc = pfmMapperFreeStruct (“Teststr1”, teststr1);

  • Related functions

    pfmMapperFreeStruct

pfmMapperFreeStructNoAlloc

Releases memory of a structure created with pfmMapperUnmarshalNoAlloc. Used when you do not need to release an entire buffer but want to allocate memory because a variable-length array is created inside.

  • Prototype

    long pfmMapperFreeStructNoAlloc(char *structName, char *structPtr)

  • Parameters

    Parameter Description

    structName

    Name of a structure for which memory is released.

    The name must be a name used when registering ProMapper. The name is case-sensitive and must be the same as that registered in Studio.

    structPtr

    Pointer to a structure for which memory is released.

  • Return values

    Return Value Description

    MAPPER_RETURN_OK

    Success

    If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    Teststr1 *teststr1;
…
rc = pfmMapperFreeStructNoAlloc(“Teststr1”, teststr1);

  • Related functions

    pfmMapperFreeStruct, pfmMapperUnmarshalNoAlloc

pfmMapperFreeMessage

Releases memory of a message that is created by marshalling. As API for all message types, separate functions need to be defined for each message type.

  • Prototype

    long pfmMapperFreeMessage(char *structName, long messageType, char *messagePtr);

  • Parameters

    Parameter Description

    structName

    Name of a structure for which memory is released.

    The name must be a name used when registering ProMapper. The name is case-sensitive and must be the same as that registered in Studio.

    messageType

    Message type. If not specified, a function macro is provided.

    • MESSAGE_FIXEDLENGTH: Fixed-length stream message

    • MESSAGE_DELIMITER: Delimiter stream message

    • MESSAGE_NAMEVALUE: FDL message

    • pfmMapperFreeMessageFixedLength: Fixed-length stream message

    • pfmMapperFreeMessageDelimiter: Delimiter stream message

    • pfmMapperFreeMessageNameValue: FDL message

    messagePtr

    Pointer to a message for which memory is released.

  • Return values

    Return Value Description

    MAPPER_RETURN_OK

    Success

    If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    char *teststr1Msg;
…
rc = pfmMapperFreeMessage(“Teststr1”, MESSAGE_FIXEDLENGTH, teststr1Msg);

/* Or, use the following function.
rc = pfmMapperFreeMessageFixedLength (“Teststr1”, teststr1Msg);
*/

  • Related functions

    pfmMapperFreeStruct

pfmMapperUnmarshal

Converts messages to structures. As API for all message types, separate functions need to be defined for each message type.

  • Prototype

    long pfmMapperUnmarshal(char *structName, long messageType, char
*messagePtr, long *messageLen, void **structPtr, long *structLen,
MapperMessageInfo *messageInfo)

  • Parameters

    Parameter Description

    structName

    Name of a structure for which memory is released.

    The name must be a name used when registering ProMapper. The name is case-sensitive and must be the same as that registered in Studio.

    messageType

    Message type. If not specified, a function macro is provided.

    • MESSAGE_FIXEDLENGTH: Fixed-length stream message

    • MESSAGE_DELIMITER: Delimiter stream message

    • MESSAGE_NAMEVALUE: FDL message

    • pfmMapperUnmarshalFixedLength: Fixed-length stream message

    • pfmMapperUnmarshalDelimiter: Delimiter stream message

    • pfmMapperUnmarshalNameValue: FDL message

    messagePtr

    Message pointer.

    messageLen

    Message length. This is used for both input and output.

    For input, set the total length of messagePtr. For output, set the number of bytes used for unmarshalling.

    structPtr

    Unmarshalled structure’s pointer reference value. This function allocates memory internally.

    After using this function, release memory by using pfmMapperFreeStruct.

    structLen

    structPtr’s size allocated with malloc. If no memory is required, set null.

    messageInfo

    Structure for options required for unmarshalling. If no option is required, set null.

  • Return values

    Return Value Description

    MAPPER_RETURN_OK

    Success

    If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    char *teststr1Msg;
Teststr1 *teststr1;
long teststr1MsgLen, teststr1Len;
…
teststr1MsgLen = strlen(teststr1Msg);
rc = pfmMapperUnmarshal("Teststr1", MESSAGE_FIXEDLENGTH, teststr1Msg,
&teststr1MsgLen, &teststr1, &teststr1Len, NULL);

/* Or, use the following function.
rc = pfmMapperUnmarshalFixedLength("Teststr1", teststr1Msg,
&teststr1MsgLen, &teststr1, &teststr1Len, NULL);
*/

  • Related functions

    pfmMapperFreeStruct, pfmMapperMarshal

pfmMapperUnmarshalNoAlloc

Converts messages to structures. Same as pfmMapperUnmarshal, but memory is not allocated. Therefore, developers need to allocate and provide a buffer.

  • Prototype

    long pfmMapperUnmarshalNoAlloc(char *structName, long messageType,
char *messagePtr, long *messageLen, void *structPtr, MapperMessageInfo
*messageInfo)

  • Parameters

    Parameter Description

    structName

    Name of a structure for which memory is released.

    The name must be a name used when registering ProMapper. The name is case-sensitive and must be the same as that registered in Studio.

    messageType

    Message type. If not specified, a function macro is provided.

    • pfmMapperUnmarshalNoAllocFixedLength: Fixed-length stream message

    • pfmMapperUnmarshalNoAllocDelimiter: Delimiter stream message

    • pfmMapperUnmarshalNoAllocNameValue: FDL message

    messagePtr

    Message pointer.

    messageLen

    Message length. This is used for both input and output.

    For input, set the total length of messagePtr. For output, set the number of bytes used for unmarshalling.

    structPtr

    Unmarshalled structure’s pointer. An externally allocated buffer is used.

    After using this function, release memory by using pfmMapperFreeStruct.

    messageInfo

    Structure for options required for unmarshalling. If no option is required, set null and enable the PMAP_FLAG_BUFF_MALLOC flag.

  • Return values

    Return Value Description

    MAPPER_RETURN_OK

    Success

    If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    char *teststr1Msg;
Teststr1 *teststr1;
long teststr1MsgLen, teststr1Len;
…
teststr1MsgLen = strlen(teststr1Msg);
rc = pfmMapperUnmarshalNoAlloc("Teststr1", MESSAGE_FIXEDLENGTH,
teststr1Msg, &teststr1MsgLen, teststr1, NULL);
/* Or, use the following function.
rc = pfmMapperUnmarshalNoAllocFixedLength("Teststr1", teststr1Msg,
&teststr1MsgLen, teststr1, NULL);
*/

  • Related functions

    pfmMapperUnmarshal, pfmMapperMarshalNoAlloc

pfmMapperMarshal

Converts structures to messages. As API for all message types, separate functions need to be defined for each message type.

  • Prototype

    long pfmMapperMarshal(char *structName, long messageType, void
*structPtr, char **messagePtr, long *messageLen, MapperMessageInfo
*messageInfo)

  • Parameters

    Parameter Description

    structName

    Name of a structure for which memory is released.

    The name must be a name used when registering ProMapper. The name is case-sensitive and must be the same as that registered in Studio.

    messageType

    Message type. If not specified, a function macro is provided.

    • MESSAGE_FIXEDLENGTH: Fixed-length stream message

    • MESSAGE_DELIMITER: Delimiter stream message

    • MESSAGE_NAMEVALUE: FDL message

    • pfmMapperMarshalFixedLength: Fixed-length stream message

    • pfmMapperMarshalDelimiter: Delimiter stream message

    • pfmMapperMarshalNameValue: FDL message

    structPtr

    Pointer to a structure to marshall.

    messagePtr

    Marshalled message’s pointer reference value. This function allocates memory internally.

    After using this function, release memory by using pfmMapperFreeMessage.

    messageLen

    Marshalled message length.

    messageInfo

    Structure for options required for marshalling. If no option is required, set null.

  • Return values

    Return Value Description

    MAPPER_RETURN_OK

    Success

    If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    Teststr1 *teststr1;
char *teststr1Msg;
long teststr1MsgLen;
…

rc = pfmMapperMarshal("Teststr1", MESSAGE_FIXEDLENGTH, teststr1,
&teststr1Msg, &teststr1MsgLen, NULL);

/* Or, use the following function.
rc = pfmMapperMarshalFixedLength ("Teststr1", teststr1, &teststr1Msg,
&teststr1MsgLen, NULL);
*/

  • Related functions

    pfmMapperFreeMessage, pfmMapperUnmarshal

pfmMapperMarshalNoAlloc

Converts structures to messages. Same as pfmMapperMarshal, but memory is not allocated. Therefore, developers need to allocate and provide a buffer.

  • Prototype

    long pfmMapperMarshalNoAlloc(char *structName, long messageType, void
*structPtr, char *messagePtr, long *messageLen, MapperMessageInfo
*messageInfo)

  • Parameters

    Parameter Description

    structName

    Name of a structure for which memory is released.

    The name must be a name used when registering ProMapper. The name is case-sensitive and must be the same as that registered in Studio.

    messageType

    Message type. If not specified, a function macro is provided.

    • pfmMapperUnmarshalNoAllocFixedLength: Fixed-length stream message

    • pfmMapperUnmarshalNoAllocDelimiter: Delimiter stream message

    • pfmMapperUnmarshalNoAllocNameValue: FDL message

    structPtr

    Pointer to a structure to marshall.

    messagePtr

    Marshalled message’s pointer. An externally allocated buffer is used.

    After using this function, release memory by using pfmMapperFreeMessage.

    messageLen

    Marshalled message length that is returned by sending the allocated buffer size of messagePtr. If this length is less than the marshalled message length, an error occurs.

    messageInfo

    Structure for options required for marshalling. If no option is required, set null and enable the PMAP_FLAG_BUFF_MALLOC flag.

  • Return values

    Return Value Description

    MAPPER_RETURN_OK

    Success

    If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    Teststr1 *teststr1;
char teststr1Msg[4096 + 1];
long teststr1MsgLen;
…

teststr1MsgLen = 4096; /* The buffer size must be passed. */
rc = pfmMapperMarshalNoAlloc("Teststr1", MESSAGE_FIXEDLENGTH,
teststr1, teststr1Msg, &teststr1MsgLen, NULL);

/* Or, use the following function.
rc = pfmMapperMarshalNoAllocFixedLength ("Teststr1", teststr1,
teststr1Msg, &teststr1MsgLen, NULL);
*/

  • Related functions

    pfmMapperFreeMessage, pfmMapperMarshal, pfmMapperUnmarshalNoAlloc

pfmMapperConv

Converts developer-defined resources according to mapping rules.

  • Prototype

    long pfmMapperConv( char *mapName,  void *input, long inputLen, void
*output, long *outputLen, long flag);

  • Parameters

    Parameter Description

    mapName

    Physical name of a map created in Studio.

    input

    Pointer to a source to convert.

    inputLen

    Source length.

    output

    Pointer to a target.

    outputLen

    Actual length of a conversion result.

    flag

    Option to allocate memory for a conversion result.

    If set to null, pfmMapperConvAlloc is used. That is, memory space for output is externally allocated and the function is called. This function does not need to allocate memory internally. Currently, NoAlloc is not supported.

  • Return values

    Return Value Description

    MAPPER_RETURN_OK

    Success

    If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    Teststr1 *source;
Teststr2 *target;
long sourceLen;
long targetLen;
sourceLen = sizeof(source);
…
rc = pfmMapperConv("Testmap", source, sourceLen, target, &targetLen, NULL);
pfmMapperGetError

Gets an error message as a string if a function returns a value that is not MAPPER_RETURN_OK.

  • Prototype

    const char *pfmMapperGetError(char *errorString)

  • Parameters

    Parameter Description

    errorString

    Non-null pointer. An error string is copied to this pointer.

  • Return values

    Error string. Since a returned pointer is a global variable in ProMapper library, pass a pointer through errorString to copy an error message.

  • Example

    printf(“error string:%s\n”, pfmMapperGetError(NULL));
pfmMapperSizeStruct

Gets the structure size.

  • Prototype

    long pfmMapperSizeStruct(char *structName)

  • Parameters

    Parameter Description

    structName

    Structure name.

  • Return values

    Structure size. If a negative value is returned, refer to ProMapper Error Codes to handle the error.

  • Example

    Teststr1 *teststr1;
…
rc = pfmMapperSizeStruct("Teststr1”);

  • Related functions

    pfmMapperSizeMessage

pfmMapperSizeMessage

Gets the message size. Used to convert the message. Used when data processing is necessary after calculating the message size first. Since this function does not convert a message, it has less overhead than getting the size after conversion.

  • Prototype

    long pfmMapperSizeMessage(char *structName, long messageType,
void *structPtr, MapperMessageInfo *messageInfo)

  • Parameters

    Parameter Description

    structName

    Name of a structure used to get the message size.

    messageType

    Message type. If not specified, a function macro is provided.

    • MESSAGE_FIXEDLENGTH: Fixed-length stream message

    • MESSAGE_DELIMITER: Delimiter stream message

    • MESSAGE_NAMEVALUE: FDL message

    • pfmMapperSizeMessageFixedLength: Fixed-length stream message

    • pfmMapperSizeMessageDelimiter: Delimiter stream message

    • pfmMapperSizeMessageNameValue: FDL message

    messageInfo

    Null.

  • Return values

    Marshalled message length. If a negative value is returned, refer to ProMapper Error Codes to handle the error.

  • Example

    Teststr1 *teststr1;
…
rc = pfmMapperSizeMessage("Teststr1", MESSAGE_FIXEDLENGTH, teststr1, NULL);
/* Or, use the following function.
rc = pfmMapperSizeMessageFixedLength("Teststr1", teststr1, NULL);
*/

  • Related functions

    pfmMapperSizeStruct

3. Variable-Length Array API

pfmVarrayAlloc

Allocates a variable-length array with a specified size.

  • Prototype

    pfmVarrayAlloc(x, nSize)

  • Parameters

    Parameter Description

    x

    Variable-length array field declared in a structure.

    nSize

    Size of a variable-length array. ProMapper internally manages array sizes.

  • Return values

    Pointer to a variable-length array. The array indexes can be accessed by using the pointer.

  • Example

    pfmVarray(long) vArray;
long *longPtr;
…
longPtr = pfmVarrayAlloc(vArray, 100);
longPtr[10] = 10L;

  • Related functions

    pfmVarrayData, pfmVarrayAppend, pfmVarrayGet, pfmVarrayElementAt

pfmVarrayData

Gets the pointer to a variable-length array.

  • Prototype

    pfmVarrayData(x)

  • Parameters

    Parameter Description

    x

    Variable-length array field declared in a structure.

  • Return values

    Pointer to a variable-length array. The array indexes can be accessed by using the pointer.

  • Example

    pfmVarray(long) vArray;
long *longPtr;
…
longPtr = pfmVarrayData(vArray);
longPtr[10] = 10L;

  • Related functions

    pfmVarrayAlloc, pfmVarrayAppend, pfmVarrayGet, pfmVarrayElementAt

pfmVarrayAppend

Appends data to the end of a variable-length array.

  • Prototype

    pfmVarrayAppend(x, elem)

  • Parameters

    Parameter Description

    x

    Variable-length array field declared in a structure.

    elem

    Pointer to an element to add.

  • Return values

    Return Value Description

    MAPPER_RETURN_OK

    Success

    If there is an error, refer to ProMapper Error Codes to handle the error.

  • Example

    pfmVarray(long) vArray;
long longVal;
…
longVal = 10L;
pfmVarrayAppend(vArray, &longVal);

  • Related functions

    pfmVarrayAlloc, pfmVarrayData, pfmVarrayGet, pfmVarrayElementAt

pfmVarrayGet

Passes the pointer to an element of a specific index in a variable-length array. For an unused area, a new memory space is allocated.

  • Prototype

    pfmVarrayGet(x, index)

  • Parameters

    Parameter Description

    x

    Variable-length array field declared in a structure.

    index

    Pointer to an element.

  • Return values

    If a return value is null, an index is a negative value or a malloc error occurs. A non-null value means success.

  • Example

    pfmVarray(long) vArray;
long *longPtr;
…
longPtr = pfmVarrayGet(vArray, 10);

  • Related functions

    pfmVarrayAlloc, pfmVarrayData, pfmVarrayAppend, pfmVarrayElementAt

pfmVarrayElementAt

Passes the pointer to an element of a specific index in a variable-length array. Same as pfmVarrayGet, but null is returned for an unused area.

  • Prototype

    pfmVarrayElementAt(x, index)

  • Parameters

    Parameter Description

    x

    Variable-length array field declared in a structure.

    index

    Pointer to an element.

  • Return values

    If a return value is null, an out-of-index error occurs. A non-null value means success.

  • Example

    pfmVarray(long) vArray;
long *longPtr;
…
longPtr = pfmVarrayElementAt(vArray, 10);

  • Related functions

    pfmVarrayAlloc, pfmVarrayData, pfmVarrayAppend, pfmVarrayGet

pfmVarrayClearCount

Initializes the number of elements in a variable-length array to 0.

  • Prototype

    pfmVarrayClearCount(x)

  • Parameters

    Parameter Description

    x

    Variable-length array field declared in a structure.

    index

    Pointer to an element.

  • Example

    pfmVarray(long) vArray;
…
pfmVarrayClearCount (vArray);

  • Related functions

    pfmVarrayCount

pfmVarrayCount

Gets the number of elements in a variable-length array.

  • Prototype

    pfmVarrayCount(x)

  • Parameters

    Parameter Description

    x

    Variable-length array field declared in a structure.

  • Return values

    Number of elements.

  • Example

    pfmVarray(long) vArray;
int count;
…
count = pfmVarrayCount(vArray);

  • Related functions

    pfmVarrayClearCount

pfmVarrayFree

Releases a buffer in a variable-length array and initializes the array.

  • Prototype

    pfmVarrayFree(x)

  • Parameters

    Parameter Description

    X

    Variable-length array field to free.

  • Example

    pfmVarray(long) vArray;
int count;
…
count = pfmVarrayFree(vArray);

  • Related functions

    pfmVarrayFree

pfmVarrayBufferSize

Gets the memory size allocated to a variable-length array.

  • Prototype

    pfmVarrayBufferSize(x)

  • Parameters

    Parameter Description

    X

    Variable-length array field declared in a structure.

  • Return values

    Allocated memory size.

  • Example

    pfmVarray(long) vArray;
int size;
…
size = pfmVarrayBufferSize(vArray);

  • Related functions

    pfmVarrayStructSize, pfmVarraySize

pfmVarrayStructSize

Gets the structure size of a variable-length array.

  • Prototype

    pfmVarrayStructSize(x)

  • Parameters

    Parameter Description

    x

    Variable-length array field declared in a structure.

  • Return values

    Structure size of a variable-length array.

  • Example

    pfmVarray(long) vArray;
int size;
…
size = pfmVarrayStructSize(vArray);

  • Related functions

    pfmVarrayBufferSize, pfmVarraySize

pfmVarraySize

Gets the size of a variable-length array.

  • Prototype

    pfmVarraySize(x)

  • Parameters

    Parameter Description

    x

    Variable-length array field declared in a structure.

  • Return values

    Size of a variable-length array.

  • Example

    pfmVarray(long) vArray;
int size;
…
size = pfmVarraySize(vArray);

  • Related functions

    pfmVarrayBufferSize, pfmVarrayStructSize