ProMapper API

본 장에서는 ProFrame에서 ProMapper 모듈을 개발하는 데 필요한 API에 대해 설명한다.

1. 개요

ProMapper와 관련된 API는 다음과 같이 2가지 유형으로 나뉜다.

일반 API

입출력 변환과 관련된 API이다.

API	설명
pfmMapperDuplicateStruct	unmarshal의 과정으로 만들어진 구조체를 복사한다.
pfmMapperNewStruct	구조체의 메모리 공간을 새로 생성할 때 사용한다.
pfmMapperFreeStruct	unmarshal의 과정으로 만들어진 구조체의 메모리를 해제한다.
pfmMapperFreeStructNoAlloc	pfmMapperUnmarshalNoAlloc로 만들어진 구조체의 메모리를 해제한다.
pfmMapperFreeMessage	marshal과정으로 만들어진 전문의 메모리를 해제한다.
pfmMapperUnmarshal	구조체 변환을 수행한다.
pfmMapperUnmarshalNoAlloc	구조체 변환을 수행하는 함수로 내부적으로 메모리 할당을 하지 않는다.
pfmMapperMarshal	전문 변환을 수행한다.
pfmMapperMarshalNoAlloc	전문 변환을 수행하는 함수로 내부적으로 메모리 할당을 하지 않는다.
pfmMapperConv	개발자가 정의한 리소스 간의 매핑 규칙대로 변환한다.
pfmMapperGetError	ProMapper API의 반환값이 MAPPER_RETURN_OK이 아닌 경우 발생되는 에러 내용을 문자열로 넘겨준다.
pfmMapperSizeStruct	구조체 크기를 반환한다.
pfmMapperSizeMessage	전문 길이를 반환한다.

API

설명

pfmMapperDuplicateStruct

unmarshal의 과정으로 만들어진 구조체를 복사한다.

pfmMapperNewStruct

구조체의 메모리 공간을 새로 생성할 때 사용한다.

pfmMapperFreeStruct

unmarshal의 과정으로 만들어진 구조체의 메모리를 해제한다.

pfmMapperFreeStructNoAlloc

pfmMapperUnmarshalNoAlloc로 만들어진 구조체의 메모리를 해제한다.

pfmMapperFreeMessage

marshal과정으로 만들어진 전문의 메모리를 해제한다.

pfmMapperUnmarshal

구조체 변환을 수행한다.

pfmMapperUnmarshalNoAlloc

구조체 변환을 수행하는 함수로 내부적으로 메모리 할당을 하지 않는다.

pfmMapperMarshal

전문 변환을 수행한다.

pfmMapperMarshalNoAlloc

전문 변환을 수행하는 함수로 내부적으로 메모리 할당을 하지 않는다.

pfmMapperConv

개발자가 정의한 리소스 간의 매핑 규칙대로 변환한다.

pfmMapperGetError

ProMapper API의 반환값이 MAPPER_RETURN_OK이 아닌 경우 발생되는 에러 내용을 문자열로 넘겨준다.

pfmMapperSizeStruct

구조체 크기를 반환한다.

pfmMapperSizeMessage

전문 길이를 반환한다.

가변배열 API

ProMapper는 가변배열을 사용하기 위해 별도의 구조체를 제공하고 있다. 개발자는 별도의 구조체를 이용해서 할당된 메모리 관리에 신경쓰지 않고 애플리케이션 프로그램을 개발할 수 있다.

pfmVarray.h 선언은 ProMapper에서 자동으로 생성되는 구조체의 헤더 파일에 만들어지고 이 필드를 가지고 가변배열 API를 이용하여 각각 배열의 인덱스에 접근할 수 있다.

API	설명
pfmVarrayAlloc	가변배열의 크기를 개발자가 명시적으로 할당할 때사용 한다.
pfmVarrayData	가변배열의 포인터를 얻는다.
pfmVarrayAppend	가변배열의 맨 끝에 데이터를 추가할 때 사용한다.
pfmVarrayGet	가변배열 내에 특정 인덱스의 element 포인터를 전달한다.
pfmVarrayElementAt	가변배열 내에 특정 인덱스의 element 포인터를 전달한다.
pfmVarrayClearCount	가변배열 내에 element 개수를 0으로 초기화한다.
pfmVarrayCount	가변배열 내에 element 개수를 반환한다.
pfmVarrayBufferSize	가변배열에 할당된 메모리 크기를 반환한다.
pfmVarrayStructSize	가변배열의 구조체 크기를 반환한다.
pfmVarraySize	가변배열의 크기를 반환한다.

API

설명

pfmVarrayAlloc

가변배열의 크기를 개발자가 명시적으로 할당할 때사용 한다.

pfmVarrayData

가변배열의 포인터를 얻는다.

pfmVarrayAppend

가변배열의 맨 끝에 데이터를 추가할 때 사용한다.

pfmVarrayGet

가변배열 내에 특정 인덱스의 element 포인터를 전달한다.

pfmVarrayElementAt

가변배열 내에 특정 인덱스의 element 포인터를 전달한다.

pfmVarrayClearCount

가변배열 내에 element 개수를 0으로 초기화한다.

pfmVarrayCount

가변배열 내에 element 개수를 반환한다.

pfmVarrayBufferSize

가변배열에 할당된 메모리 크기를 반환한다.

pfmVarrayStructSize

가변배열의 구조체 크기를 반환한다.

pfmVarraySize

가변배열의 크기를 반환한다.

2. 일반 API

pfmMapperDuplicateStruct

unmarshal의 과정으로 만들어진 구조체를 복사하는 함수이다. 구조체 내에 가변배열이 있을 경우 별도의 메모리를 할당하여 복사한다.

프로토타입

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

파라미터

파라미터명	설명
structName	복사를 수행할 구조체명이다. ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영 향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.
sourceStructPtr	복사할 원본 구조체 포인터이다.
targetStructPtr	복사 후 메모리가 할당될 구조체 포인터의 참조 값이다.

파라미터명

설명

structName

복사를 수행할 구조체명이다.

ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영 향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.

sourceStructPtr

복사할 원본 구조체 포인터이다.

targetStructPtr

복사 후 메모리가 할당될 구조체 포인터의 참조 값이다.

반환값

구조체를 복사하는데 문제가 없을 경우 MAPPER_RETURN_OK 코드가 반환된다. 그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

예제

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

관련 API

pfmMapperFreeStruct

pfmMapperNewStruct

구조체의 메모리 공간을 새로 생성할 때 사용한다. 생성된 메모리는 0x00으로 초기화된다.

프로토타입

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

파라미터

파라미터명	설명
structName	복사를 수행할 구조체명이다. ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.
targetStructPtr	메모리가 할당될 구조체 포인터의 참조 값이다.

파라미터명

설명

structName

복사를 수행할 구조체명이다. ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.

targetStructPtr

메모리가 할당될 구조체 포인터의 참조 값이다.

반환값

반환값 설명

MAPPER_RETURN_OK

정상

그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

반환값	설명
MAPPER_RETURN_OK	정상

예제

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

관련 API

pfmMapperDuplicateStruct

pfmMapperFreeStruct

Unmarshal의 과정으로 만들어진 구조체의 메모리를 해제하는 함수이다.

프로토타입

long pfmMapperFreeStruct(char *structName, char *structPtr)

파라미터

파라미터명	설명
structName	메모리 해제를 수행할 구조체명이다. ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.
structPtr	메모리를 해제할 구조체 포인터이다.

파라미터명

설명

structName

메모리 해제를 수행할 구조체명이다.

ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.

structPtr

메모리를 해제할 구조체 포인터이다.

반환값

반환값 설명

MAPPER_RETURN_OK

정상

그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

반환값	설명
MAPPER_RETURN_OK	정상

예제

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

관련 API

pfmMapperFreeStruct

pfmMapperFreeStructNoAlloc

pfmMapperUnmarshalNoAlloc로 만들어진 구조체의 메모리를 해제하는 함수이다. 전체 버퍼는 해제할 필요가 없으나 내부에 가변배열이 생겨 메모리 할당이 발생한 경우를 위해 사용한다.

프로토타입

long pfmMapperFreeStructNoAlloc(char *structName, char *structPtr)

파라미터

파라미터명	설명
structName	메모리 해제를 수행할 구조체명이다. ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.
structPtr	메모리를 해제할 구조체 포인터이다.

파라미터명

설명

structName

메모리 해제를 수행할 구조체명이다.

ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.

structPtr

메모리를 해제할 구조체 포인터이다.

반환값

반환값

MAPPER_RETURN_OK

정상

그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

반환값
MAPPER_RETURN_OK	정상

예제

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

관련 API

pfmMapperFreeStruct, pfmMapperUnmarshalNoAlloc

pfmMapperFreeMessage

Marshal의 과정으로 만들어진 전문의 메모리를 해제하는 함수이다. 모든 전문 타입에 사용할 수 있는 범용 API로 각 전문 타입에 맞는 별도의 함수가 정의되어야 한다.

프로토타입

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

파라미터

파라미터명	설명
structName	메모리 해제를 수행할 구조체명이다. ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.
messageType	범용 API 함수로서 전문 타입을 직접 입력받는다. MESSAGE_FIXEDLENGTH : 고정 길이 Stream 전문 MESSAGE_DELIMITER: Delimiter Stream 전문 MESSAGE_NAMEVALUE: FDL 전문(각 전문 타입별로 messageType을 입력하지 않는 Function Macro를 제공한다.) pfmMapperFreeMessageFixedLength: 고정 길이 Stream 전문 pfmMapperFreeMessageDelimiter: Delimiter Stream 전문 pfmMapperFreeMessageNameValue: FDL 전문
messagePtr	메모리를 해제할 전문 포인터이다.

파라미터명

설명

structName

메모리 해제를 수행할 구조체명이다.

ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.

messageType

범용 API 함수로서 전문 타입을 직접 입력받는다.

MESSAGE_FIXEDLENGTH : 고정 길이 Stream 전문
MESSAGE_DELIMITER: Delimiter Stream 전문
MESSAGE_NAMEVALUE: FDL 전문(각 전문 타입별로 messageType을 입력하지 않는 Function Macro를 제공한다.)
pfmMapperFreeMessageFixedLength: 고정 길이 Stream 전문
pfmMapperFreeMessageDelimiter: Delimiter Stream 전문
pfmMapperFreeMessageNameValue: FDL 전문

messagePtr

메모리를 해제할 전문 포인터이다.

반환값

반환값 설명

MAPPER_RETURN_OK

정상

그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

반환값	설명
MAPPER_RETURN_OK	정상

예제

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

/* 또는 아래 API 함수를 사용한다.
rc = pfmMapperFreeMessageFixedLength (“Teststr1”, teststr1Msg);
*/

관련 API

pfmMapperFreeStruct

pfmMapperUnmarshal

구조체 변환(“전문 → 구조체”)을 수행하는 함수이다. 모든 전문 타입에 사용할 수 있는 범용 API로 각 전문 타입에 맞는 별도의 함수가 정의되어야 한다.

프로토타입

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

파라미터

파라미터명	설명
structName	메모리 해제를 수행할 구조체명이다. ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.
messageType	범용 API로서 전문 타입을 직접 입력받는다. MESSAGE_FIXEDLENGTH: 고정 길이 Stream 전문 MESSAGE_DELIMITER: Delimiter Stream 전문 MESSAGE_NAMEVALUE: FDL 전문(각 전문 타입별로 messageType을 입력하지 않는 Function Macro를 제공한다.) pfmMapperUnmarshalFixedLength: 고정 길이 Stream 전문 pfmMapperUnmarshalDelimiter: Delimiter Stream 전문 pfmMapperUnmarshalNameValue: FDL 전문
messagePtr	전문 포인터이다.
messageLen	전문의 전체 길이로 입출력 모두 사용된다. 입력의 경우 messagePtr의 전체 길이를 설정해야 하고 출력의 경우 messagePtr 중 Unmarshal에서 사용한 바이트 수를 설정해야 한다.
structPtr	Unmarshal된 구조체의 포인터 참조 값으로 함수 내부적으로 메모리 할당 을 수행한다. 해당 함수를 사용한 후에는 pfmMapperFreeStruct API를 이용하여 할당된 메모리를 해제해야 한다.
structLen	structPtr의 malloc된 크기이며, 받을 필요가 없는 경우 NULL을 설정한다.
messageInfo	Unmarshal할 때 필요한 옵션을 설정하는 구조체이다. 별도의 옵션이 필요 없는 경우 NULL을 설정한다.

파라미터명

설명

structName

메모리 해제를 수행할 구조체명이다.

ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.

messageType

범용 API로서 전문 타입을 직접 입력받는다.

MESSAGE_FIXEDLENGTH: 고정 길이 Stream 전문
MESSAGE_DELIMITER: Delimiter Stream 전문
MESSAGE_NAMEVALUE: FDL 전문(각 전문 타입별로 messageType을 입력하지 않는 Function Macro를 제공한다.)
pfmMapperUnmarshalFixedLength: 고정 길이 Stream 전문
pfmMapperUnmarshalDelimiter: Delimiter Stream 전문
pfmMapperUnmarshalNameValue: FDL 전문

messagePtr

전문 포인터이다.

messageLen

전문의 전체 길이로 입출력 모두 사용된다.

입력의 경우 messagePtr의 전체 길이를 설정해야 하고 출력의 경우 messagePtr 중 Unmarshal에서 사용한 바이트 수를 설정해야 한다.

structPtr

Unmarshal된 구조체의 포인터 참조 값으로 함수 내부적으로 메모리 할당 을 수행한다.

해당 함수를 사용한 후에는 pfmMapperFreeStruct API를 이용하여 할당된 메모리를 해제해야 한다.

structLen

structPtr의 malloc된 크기이며, 받을 필요가 없는 경우 NULL을 설정한다.

messageInfo

Unmarshal할 때 필요한 옵션을 설정하는 구조체이다. 별도의 옵션이 필요 없는 경우 NULL을 설정한다.

반환값

반환값 설명

MAPPER_RETURN_OK

정상

그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

반환값	설명
MAPPER_RETURN_OK	정상

예제

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

/* 또는 아래 API 함수를 사용한다.
rc = pfmMapperUnmarshalFixedLength("Teststr1", teststr1Msg,
&teststr1MsgLen, &teststr1, &teststr1Len, NULL);
*/

관련 API

pfmMapperFreeStruct, pfmMapperMarshal

pfmMapperUnmarshalNoAlloc

구조체 변환(“전문 → 구조체”)을 수행하는 함수이다. pfmMapperUnmarshal 함수와 동일한 역할을 수행하나 구조체를 변환하는 경우 내부적으로 메모리 할당을 하지 않으므로 개발자가 버퍼를 할당해서 넘겨줘야 하는 것이 다르다.

프로토타입

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

파라미터

파라미터명	설명
structName	메모리 해제를 수행할 구조체명이다. ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.
messageType	범용 API로서 전문 타입을 직접 입력받는다. 각 전문 타입별로 messageType을 입력하지 않는 경우 Function Macro를 제공한다. pfmMapperUnmarshalNoAllocFixedLength: 고정 길이 Stream 전문 pfmMapperUnmarshalNoAllocDelimiter: Delimiter Stream 전문 pfmMapperUnmarshalNoAllocNameValue: FDL 전문
messagePtr	전문 포인터이다.
messageLen	전문의 전체 길이로 입출력 모두 사용된다. 입력의 경우 messagePtr의 전체 길이를 설정해야 하고 출력의 경우 messagePtr 중 unmarshal에서 사용한 바이트 수를 설정해야 한다.
structPtr	Unmarshal된 구조체의 포인터로 외부에서 할당된 버퍼를 사용한다. 해당 함수를 사용한 후에는 pfmMapperFreeStruct API를 이용하여 할당된 메모리를 해제해야 한다.
messageInfo	Unmarshal할 때 필요한 옵션을 설정하는 구조체이다. 별도의 옵션이 필요없는 경우 NULL을 설정한다. NULL을 설정할 때는 내부적으로 PMAP_FLAG_BUFF_MALLOC flag를 켜준다.

파라미터명

설명

structName

메모리 해제를 수행할 구조체명이다.

ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.

messageType

범용 API로서 전문 타입을 직접 입력받는다.

각 전문 타입별로 messageType을 입력하지 않는 경우 Function Macro를 제공한다.

pfmMapperUnmarshalNoAllocFixedLength: 고정 길이 Stream 전문
pfmMapperUnmarshalNoAllocDelimiter: Delimiter Stream 전문
pfmMapperUnmarshalNoAllocNameValue: FDL 전문

messagePtr

전문 포인터이다.

messageLen

전문의 전체 길이로 입출력 모두 사용된다.

입력의 경우 messagePtr의 전체 길이를 설정해야 하고 출력의 경우 messagePtr 중 unmarshal에서 사용한 바이트 수를 설정해야 한다.

structPtr

Unmarshal된 구조체의 포인터로 외부에서 할당된 버퍼를 사용한다.

해당 함수를 사용한 후에는 pfmMapperFreeStruct API를 이용하여 할당된 메모리를 해제해야 한다.

messageInfo

Unmarshal할 때 필요한 옵션을 설정하는 구조체이다. 별도의 옵션이 필요없는 경우 NULL을 설정한다.

NULL을 설정할 때는 내부적으로 PMAP_FLAG_BUFF_MALLOC flag를 켜준다.

반환값

반환값

MAPPER_RETURN_OK

정상

그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

반환값
MAPPER_RETURN_OK	정상

예제

char *teststr1Msg;
Teststr1 *teststr1;
long teststr1MsgLen, teststr1Len;
…
teststr1MsgLen = strlen(teststr1Msg);
rc = pfmMapperUnmarshalNoAlloc("Teststr1", MESSAGE_FIXEDLENGTH,
teststr1Msg, &teststr1MsgLen, teststr1, NULL);
/* 또는 아래 API 함수를 사용한다.
rc = pfmMapperUnmarshalNoAllocFixedLength("Teststr1", teststr1Msg,
&teststr1MsgLen, teststr1, NULL);
*/

관련 API

pfmMapperUnmarshal, pfmMapperMarshalNoAlloc

pfmMapperMarshal

전문 변환(“구조체 → 전문”)을 수행하는 함수이다. 모든 전문 타입에 사용할 수 있는 범용 API로 각 전문 타입에 맞는 별도의 함수가 정의되어 있어야 한다.

프로토타입

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

파라미터

파라미터명	설명
structName	메모리 해제를 수행할 구조체명이다. ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.
messageType	범용 API로서 전문 타입을 직접 입력받는다. MESSAGE_FIXEDLENGTH: 고정 길이 Stream 전문 MESSAGE_DELIMITER: Delimiter Stream 전문 MESSAGE_NAMEVALUE: FDL 전문(각 전문 타입별로 messageType을 입력하지 않는 Function Macro를 제공한다.) pfmMapperMarshalFixedLength: 고정 길이 Stream 전문 pfmMapperMarshalDelimiter: Delimiter Stream 전문 pfmMapperMarshalNameValue: FDL 전문
structPtr	Marshal를 수행할 구조체 포인터이다.
messagePtr	Marshal된 구조체의 포인터 참조 값으로 함수 내부적으로 메모리 할당을 수행한다. 해당 함수를 사용한 후에는 pfmMapperFreeMessage API를 이용하여 할당된 메모리를 해제해야 한다.
messageLen	Marshal된 전문 전체 길이이다.
messageInfo	Unmarshal할 때 필요한 옵션을 설정하는 구조체이다. 별도의 옵션이 필요 없는 경우 NULL을 설정한다.

파라미터명

설명

structName

메모리 해제를 수행할 구조체명이다.

ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.

messageType

범용 API로서 전문 타입을 직접 입력받는다.

MESSAGE_FIXEDLENGTH: 고정 길이 Stream 전문
MESSAGE_DELIMITER: Delimiter Stream 전문
MESSAGE_NAMEVALUE: FDL 전문(각 전문 타입별로 messageType을 입력하지 않는 Function Macro를 제공한다.)
pfmMapperMarshalFixedLength: 고정 길이 Stream 전문
pfmMapperMarshalDelimiter: Delimiter Stream 전문
pfmMapperMarshalNameValue: FDL 전문

structPtr

Marshal를 수행할 구조체 포인터이다.

messagePtr

Marshal된 구조체의 포인터 참조 값으로 함수 내부적으로 메모리 할당을 수행한다. 해당 함수를 사용한 후에는 pfmMapperFreeMessage API를 이용하여 할당된 메모리를 해제해야 한다.

messageLen

Marshal된 전문 전체 길이이다.

messageInfo

Unmarshal할 때 필요한 옵션을 설정하는 구조체이다. 별도의 옵션이 필요 없는 경우 NULL을 설정한다.

반환값

반환값 설명

MAPPER_RETURN_OK

정상

그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

반환값	설명
MAPPER_RETURN_OK	정상

예제

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

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

/* 또는 아래 API 함수를 사용한다.
rc = pfmMapperMarshalFixedLength ("Teststr1", teststr1, &teststr1Msg,
&teststr1MsgLen, NULL);
*/

관련 API

pfmMapperFreeMessage, pfmMapperUnmarshal

pfmMapperMarshalNoAlloc

전문 변환(“구조체 → 전문”)을 수행하는 함수이다. pfmMapperMarshal 함수와 동일한 역할을 수행하나 전문 변환을 할 때 내부적으로 메모리 할당을 하지 않으므로 개발자가 버퍼를 할당해서 넘겨줘야 한다.

프로토타입

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

파라미터

파라미터명	설명
structName	메모리 해제를 수행할 구조체명이다. ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.
messageType	범용 API로서 전문 타입을 직접 입력받는다. 각 전문 타입별로 messageType을 입력하지 않는 Function Macro를 제공 한다. pfmMapperUnmarshalNoAllocFixedLength: 고정 길이 Stream 전문 pfmMapperUnmarshalNoAllocDelimiter: Delimiter Stream 전문 pfmMapperUnmarshalNoAllocNameValue: FDL 전문
structPtr	Marshal를 수행할 구조체 포인터이다.
messagePtr	Marshal된 전문 포인터로 외부에서 할당된 버퍼를 사용한다. 해당 함수를 사용한 후에는 pfmMapperFreeMessage API를 이용하여 할당된 메모리를 해제해야 한다.
messageLen	messagePtr의 할당된 버퍼 크기를 넘겨주고 반환값으로 Marshal된 길이를 얻는다. 해당 길이가 Marshal된 길이보다 짧을 경우 에러가 발생된다.
messageInfo	Unmarshal할 때 필요한 옵션을 설정하는 구조체이다. 별도의 옵션이 필요없는 경우 NULL을 설정한다. NULL을 설정할 때 내부적으로 PMAP_FLAG_BUFF_MALLOC flag를 켜준다.

파라미터명

설명

structName

메모리 해제를 수행할 구조체명이다.

ProMapper를 등록할 때 사용한 구조체명을 넘겨준다. 구조체명은 대소문자에 영향을 받으므로 스튜디오에 등록된 이름과 반드시 일치해야 한다.

messageType

범용 API로서 전문 타입을 직접 입력받는다.

각 전문 타입별로 messageType을 입력하지 않는 Function Macro를 제공 한다.

pfmMapperUnmarshalNoAllocFixedLength: 고정 길이 Stream 전문
pfmMapperUnmarshalNoAllocDelimiter: Delimiter Stream 전문
pfmMapperUnmarshalNoAllocNameValue: FDL 전문

structPtr

Marshal를 수행할 구조체 포인터이다.

messagePtr

Marshal된 전문 포인터로 외부에서 할당된 버퍼를 사용한다.

해당 함수를 사용한 후에는 pfmMapperFreeMessage API를 이용하여 할당된 메모리를 해제해야 한다.

messageLen

messagePtr의 할당된 버퍼 크기를 넘겨주고 반환값으로 Marshal된 길이를 얻는다. 해당 길이가 Marshal된 길이보다 짧을 경우 에러가 발생된다.

messageInfo

Unmarshal할 때 필요한 옵션을 설정하는 구조체이다. 별도의 옵션이 필요없는 경우 NULL을 설정한다.

NULL을 설정할 때 내부적으로 PMAP_FLAG_BUFF_MALLOC flag를 켜준다.

반환값

반환값 설명

MAPPER_RETURN_OK

정상

그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

반환값	설명
MAPPER_RETURN_OK	정상

예제

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

teststr1MsgLen = 4096; /* 반드시 버퍼 크기를 넘겨줘야 함 */
rc = pfmMapperMarshalNoAlloc("Teststr1", MESSAGE_FIXEDLENGTH,
teststr1, teststr1Msg, &teststr1MsgLen, NULL);

/* 또는 아래 API 함수를 사용한다.
rc = pfmMapperMarshalNoAllocFixedLength ("Teststr1", teststr1,
teststr1Msg, &teststr1MsgLen, NULL);
*/

관련 API

pfmMapperFreeMessage, pfmMapperMarshal, pfmMapperUnmarshalNoAlloc

pfmMapperConv

개발자가 정의한 리소스 간의 매핑 규칙대로 변환하는 함수이다.

프로토타입

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

파라미터

파라미터명	설명
mapName	스튜디오에서 만든 맵의 물리명이다.
input	변환의 source pointer이다.
inputLen	소스 길이이다.
output	변환의 target pointer이다.
outputLen	변환 후 결과값에 대한 실제 길이를 반환한다.
flag	결과값에 대한 메모리 할당 여부를 설정한다. 만약 이 플래그의 값이 NULL일 때는 pfmMapperConvAlloc 함수로 동작된다. 즉, 외부에서 output에 대한 메모리 공간을 주고 함수를 호출하므로 API 내부에서 메모리를 할당하지 않아도 된다는 뜻이다. 현재 NoAlloc은 지원하지 않는다.

파라미터명

설명

mapName

스튜디오에서 만든 맵의 물리명이다.

input

변환의 source pointer이다.

inputLen

소스 길이이다.

output

변환의 target pointer이다.

outputLen

변환 후 결과값에 대한 실제 길이를 반환한다.

flag

결과값에 대한 메모리 할당 여부를 설정한다.

만약 이 플래그의 값이 NULL일 때는 pfmMapperConvAlloc 함수로 동작된다. 즉, 외부에서 output에 대한 메모리 공간을 주고 함수를 호출하므로 API 내부에서 메모리를 할당하지 않아도 된다는 뜻이다. 현재 NoAlloc은 지원하지 않는다.

반환값

반환값 설명

MAPPER_RETURN_OK

정상

그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

반환값	설명
MAPPER_RETURN_OK	정상

예제

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

pfmMapperGetError

위에서 언급된 함수들의 반환값이 MAPPER_RETURN_OK이 아닌 경우 발생되는 에러 내용을 문자열로 넘겨주는 함수이다.

프로토타입

const char *pfmMapperGetError(char *errorString)

파라미터

파라미터명 설명

errorString

NULL이 아닌 포인터를 전달하면 에러 내용을 문자열로 복사한다.
반환값

에러 내용을 문자열로 반환한다. 반환된 포인터는 ProMapper 라이브러리 내의 전역변수이므로 해당 문자열을 저장하고자 할 때는 errorString에 포인터를 전달해서 복사되도록 한다.

파라미터명	설명
errorString	NULL이 아닌 포인터를 전달하면 에러 내용을 문자열로 복사한다.

예제

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

pfmMapperSizeStruct

구조체 크기를 반환하는 함수이다.

프로토타입

long pfmMapperSizeStruct(char *structName)

파라미터

파라미터명 설명

structName

구조체 크기를 반환할 구조체명이다.
반환값

구조체 크기를 반환한다. 만약 음수로 구조체 크기가 반환되면 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

파라미터명	설명
structName	구조체 크기를 반환할 구조체명이다.

예제

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

관련 API

pfmMapperSizeMessage

pfmMapperSizeMessage

전문 변환을 수행할 때 전문 길이를 반환하는 함수이다. 그러나 실제로 전문 변환을 수행하지 않고 전문 길이만 계산하므로 전문 변환 수행 후의 전문 길이를 반환받는 것보다 오버헤드가 작다. 전문 길이를 먼저 계산해서 전문에 설정한 후 데이터 처리가 필요할 경우에 사용한다.

프로토타입

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

파라미터

파라미터명	설명
structName	전문 길이를 반환할 구조체명이다.
messageType	범용 API로서 전문 타입을 직접 입력받는다. MESSAGE_FIXEDLENGTH: 고정 길이 Stream 전문 MESSAGE_DELIMITER: Delimiter Stream 전문 MESSAGE_NAMEVALUE: FDL 전문(각 전문 타입별로 messageType을 입력하지 않는 Function Macro를 제공한다.) pfmMapperSizeMessageFixedLength:고정 길이 Stream 전문 pfmMapperSizeMessageDelimiter: Delimiter Stream 전문 pfmMapperSizeMessageNameValue: FDL 전문
messageInfo	NULL을 설정한다.

파라미터명

설명

structName

전문 길이를 반환할 구조체명이다.

messageType

범용 API로서 전문 타입을 직접 입력받는다.

MESSAGE_FIXEDLENGTH: 고정 길이 Stream 전문
MESSAGE_DELIMITER: Delimiter Stream 전문
MESSAGE_NAMEVALUE: FDL 전문(각 전문 타입별로 messageType을 입력하지 않는 Function Macro를 제공한다.)
pfmMapperSizeMessageFixedLength:고정 길이 Stream 전문
pfmMapperSizeMessageDelimiter: Delimiter Stream 전문
pfmMapperSizeMessageNameValue: FDL 전문

messageInfo

NULL을 설정한다.

반환값

Marshal된 전문 길이를 반환한다. 만약 음수로 구조체 크기가 반환되면 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

예제

Teststr1 *teststr1;
…
rc = pfmMapperSizeMessage("Teststr1", MESSAGE_FIXEDLENGTH, teststr1, NULL);
/* 또는 아래 API 함수를 사용한다.
rc = pfmMapperSizeMessageFixedLength("Teststr1", teststr1, NULL);
*/

관련 API

pfmMapperSizeStruct

3. 가변배열 API

pfmVarrayAlloc

가변배열의 크기를 사용자가 명시적으로 할당할 때 사용한다.

프로토타입
```
pfmVarrayAlloc(x, nSize)
```

파라미터

파라미터명	설명
x	구조체에 선언된 가변배열 필드를 전달한다.
nSize	몇 개의 배열을 할당할 것인지 설정하는 것으로 ProMapper 내부적으로 배 열 크기가 관리되고 있기 때문에 이에 맞게 동작한다.

파라미터명

설명

구조체에 선언된 가변배열 필드를 전달한다.

nSize

몇 개의 배열을 할당할 것인지 설정하는 것으로 ProMapper 내부적으로 배 열 크기가 관리되고 있기 때문에 이에 맞게 동작한다.

반환값

가변배열의 포인터를 반환한다. 해당 포인터를 전달받아 직접 배열 인덱스에 접근한다.

예제

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

관련 API

pfmVarrayData, pfmVarrayAppend, pfmVarrayGet, pfmVarrayElementAt

pfmVarrayData

가변배열의 포인터를 얻는 함수이다.

프로토타입
```
pfmVarrayData(x)
```
파라미터

파라미터명 설명

x

구조체에 선언된 가변배열 필드를 전달한다.
반환값

가변배열의 포인터를 반환한다. 해당 포인터를 전달받아 직접 배열 인덱스에 접근한다.

파라미터명	설명
x	구조체에 선언된 가변배열 필드를 전달한다.

예제

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

관련 API

pfmVarrayAlloc, pfmVarrayAppend, pfmVarrayGet, pfmVarrayElementAt

pfmVarrayAppend

가변배열 맨 끝에 데이터를 추가할 때 사용하는 함수이다.

프로토타입
```
pfmVarrayAppend(x, elem)
```
파라미터

파라미터명 설명

x

구조체에 선언된 가변배열 필드를 전달한다.

elem

추가할 element의 포인터를 전달한다.
반환값

반환값

MAPPER_RETURN_OK

정상

그 외는 ProMapper 에러코드를 참고하여 발생된 오류를 해결한다.

파라미터명	설명
x	구조체에 선언된 가변배열 필드를 전달한다.
elem	추가할 element의 포인터를 전달한다.

반환값
MAPPER_RETURN_OK	정상

예제

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

관련 API

pfmVarrayAlloc, pfmVarrayData, pfmVarrayGet, pfmVarrayElementAt

pfmVarrayGet

가변배열 내에 특정 인덱스의 element 포인터를 전달하는 함수이다. 기존에 사용되지 않는 영역일 때는 새로 메모리 공간을 할당한다.

프로토타입
```
pfmVarrayGet(x, index)
```
파라미터

파라미터명 설명

x

구조체에 선언된 가변배열 필드를 전달한다.

index

추가할 element의 포인터를 전달한다.
반환값

반환값이 NULL인 경우 index가 음수이거나 malloc 에러가 발생된다. 그 외는 정상이다.

파라미터명	설명
x	구조체에 선언된 가변배열 필드를 전달한다.
index	추가할 element의 포인터를 전달한다.

예제

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

관련 API

pfmVarrayAlloc, pfmVarrayData, pfmVarrayAppend, pfmVarrayElementAt

pfmVarrayElementAt

가변배열 내에 특정 인덱스의 element 포인터를 전달하는 함수이다. 기존에 사용되지 않는 영역일 때는 NULL을 반환한다. 이와 같은 내용이 pfmVarrayGet 함수와 다른 점이다.

프로토타입
```
pfmVarrayElementAt(x, index)
```
파라미터

파라미터명 설명

x

구조체에 선언된 가변배열 필드를 전달한다.

index

추가할 element의 포인터를 전달한다.
반환값

반환값이 NULL인 경우 out-of-index 에러가 발생된다. 그 외는 정상이다.

파라미터명	설명
x	구조체에 선언된 가변배열 필드를 전달한다.
index	추가할 element의 포인터를 전달한다.

예제

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

관련 API

pfmVarrayAlloc, pfmVarrayData, pfmVarrayAppend, pfmVarrayGet

pfmVarrayClearCount

가변배열 내의 element 개수를 0으로 초기화하는 함수이다.

프로토타입
```
pfmVarrayClearCount(x)
```
파라미터

파라미터명 설명

x

구조체에 선언된 가변배열 필드를 전달한다.

index

추가할 element의 포인터를 전달한다.

파라미터명	설명
x	구조체에 선언된 가변배열 필드를 전달한다.
index	추가할 element의 포인터를 전달한다.

예제

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

관련 API

pfmVarrayCount

pfmVarrayCount

가변배열 내의 element 개수를 반환하는 함수이다.

프로토타입
```
pfmVarrayCount(x)
```
파라미터

파라미터명 설명

x

구조체에 선언된 가변배열 필드를 전달한다.
반환값

element 개수를 반환한다.

파라미터명	설명
x	구조체에 선언된 가변배열 필드를 전달한다.

예제

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

관련 API

pfmVarrayClearCount

pfmVarrayFree

가변배열 내의 버퍼를 해제하고 가변배열 전체를 초기화한다.

프로토타입
```
pfmVarrayFree(x)
```
파라미터

파라미터명 설명

X

Free할 가변배열 필드를 전달한다.

파라미터명	설명
X	Free할 가변배열 필드를 전달한다.

예제

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

관련 API

pfmVarrayFree

pfmVarrayBufferSize

가변배열에 할당된 메모리 크기를 반환하는 함수이다.

프로토타입
```
pfmVarrayBufferSize(x)
```
파라미터

파라미터명 설명

X

구조체에 선언된 가변배열 필드를 전달한다.
반환값

할당된 메모리 크기를 반환한다.

파라미터명	설명
X	구조체에 선언된 가변배열 필드를 전달한다.

예제

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

관련 API

pfmVarrayStructSize, pfmVarraySize

pfmVarrayStructSize

가변배열의 구조체 크기를 반환하는 함수이다.

프로토타입
```
pfmVarrayStructSize(x)
```
파라미터

파라미터명 설명

x

구조체에 선언된 가변배열 필드를 전달한다.
반환값

가변배열의 구조체 크기를 반환한다.

파라미터명	설명
x	구조체에 선언된 가변배열 필드를 전달한다.

예제

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

관련 API

pfmVarrayBufferSize, pfmVarraySize

pfmVarraySize

가변배열의 크기를 반환하는 함수이다.

프로토타입
```
pfmVarraySize(x)
```
파라미터

파라미터명 설명

x

구조체에 선언된 가변배열 필드를 전달한다.
반환값

가변배열의 크기를 반환한다.

파라미터명	설명
x	구조체에 선언된 가변배열 필드를 전달한다.

예제

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

관련 API

pfmVarrayBufferSize, pfmVarrayStructSize