API

본 장에서는 실제 애플리케이션 개발을 위한 API의 사용법에 대해서 소개한다.

1. 개요

Tmax SQ 시스템에서 제공하는 API는 SQ를 사용하기 위한 API, GQ를 사용하기 위한 API, 키 리스트 및 세션에 대한 조회를 위한 API로 나뉜다. SQ API("tmax_sq_"로 시작)와 GQ API("max_gq_"로 시작)는 함수 이름만 다르고 동일한 방식으로 수행된다.

다음은 각 API별 목록이다.

SQ API

API	설명
tmax_sq_put	서버 데이터를 세션 큐에 저장한다.
tmax_sq_get	데이터를 세션 큐에 저장한다.
tmax_sq_count	현재 SQ에 저장된 데이터 개수를 반환한다.
tmax_sq_purge	SQ의 데이터를 삭제한다.
tmax_sq_keygen	시스템 키 생성 및 가져온다.
tmax_sq_getkeylist	현 세션 SQ의 키 리스트를 가져온다.

API

설명

tmax_sq_put

서버 데이터를 세션 큐에 저장한다.

tmax_sq_get

데이터를 세션 큐에 저장한다.

tmax_sq_count

현재 SQ에 저장된 데이터 개수를 반환한다.

tmax_sq_purge

SQ의 데이터를 삭제한다.

tmax_sq_keygen

시스템 키 생성 및 가져온다.

tmax_sq_getkeylist

현 세션 SQ의 키 리스트를 가져온다.

GQ API

API	설명
tmax_gq_put	데이터를 GQ에 저장한다.
tmax_gq_get	GQ에서 데이터를 가져온다.
tmax_gq_count	GQ에 저장된 데이터의 개수를 반환한다.
tmax_gq_purge	GQ의 데이터를 삭제한다.
tmax_gq_keygen	시스템 키 생성 및 가져온다.
tmax_gq_getkeylist	GQ의 키 리스트를 가져온다.

API

설명

tmax_gq_put

데이터를 GQ에 저장한다.

tmax_gq_get

GQ에서 데이터를 가져온다.

tmax_gq_count

GQ에 저장된 데이터의 개수를 반환한다.

tmax_gq_purge

GQ의 데이터를 삭제한다.

tmax_gq_keygen

시스템 키 생성 및 가져온다.

tmax_gq_getkeylist

GQ의 키 리스트를 가져온다.

키 리스트 및 세션 조회 API

API	설명
tmax_get_sessionid	현 세션의 ID를 반환한다.
tmax_keylist_count	keylist 핸들로부터 키 리스트의 개수를 반환한다.
tmax_keylist_getakey	keylist 핸들로부터 n번째 키 정보를 가져온다.
tmax_keylist_free	keylist 핸들의 메모리나 기타 자원들을 해제한다.

API

설명

tmax_get_sessionid

현 세션의 ID를 반환한다.

tmax_keylist_count

keylist 핸들로부터 키 리스트의 개수를 반환한다.

tmax_keylist_getakey

keylist 핸들로부터 n번째 키 정보를 가져온다.

tmax_keylist_free

keylist 핸들의 메모리나 기타 자원들을 해제한다.

각 API 설명 중 에러 코드에 대한 자세한 내용은 Tmax Application Development Guide를 참고한다.

2. SQ API

2.1. tmax_sq_put

서버 데이터를 SQ에 저장하는 함수로서 키와 데이터 값을 전달해야 한다.

프로토타입

#include <tmaxapi.h>
int tmax_sq_put(char *key, long keylenl, char *data, long lenl, long flagsl)

파라미터

파라미터	설명
key	SQ에 저장할 데이터를 위한 키 값을 저장할 버퍼이다.
keylenl	키 버퍼의 크기를 지정한다. (단위: Byte)
data	SQ에 저장할 데이터를 담고 있는 버퍼로 반드시 tpalloc()으로 할당된 버퍼에 대한 포인터이어야 한다.
lenl	SQ에 저장할 데이터 버퍼의 크기를 지정한다. (단위: Byte)
flagsl	다음은 flagsl에 설정되는 값에 대한 설명이다. TPSQ_UPDATE 키 값이 같을 경우 업데이트한다. flags가 설정되어 있지 않으면 TPEMATCH 에러가 반환된다. TPSQ_SYSKEY tmax_sq_keygen()를 통해 생성된 시스템 키를 사용할 경우 설정한다. TPSQ_KEYGEN 시스템 키를 자동으로 생성하여 저장한다. 키(key)는 SQ_SYSKEY_SIZE 크기(keylenl = SQ_SYSKEY_SIZE)로 할당해야 한다. 성공적으로 수행했을 경우 키에 생성된 키 값이 저장된다.

설명

key

SQ에 저장할 데이터를 위한 키 값을 저장할 버퍼이다.

keylenl

키 버퍼의 크기를 지정한다. (단위: Byte)

data

SQ에 저장할 데이터를 담고 있는 버퍼로 반드시 tpalloc()으로 할당된 버퍼에 대한 포인터이어야 한다.

lenl

SQ에 저장할 데이터 버퍼의 크기를 지정한다. (단위: Byte)

flagsl

다음은 flagsl에 설정되는 값에 대한 설명이다.

TPSQ_UPDATE

키 값이 같을 경우 업데이트한다. flags가 설정되어 있지 않으면 TPEMATCH 에러가 반환된다.
TPSQ_SYSKEY

tmax_sq_keygen()를 통해 생성된 시스템 키를 사용할 경우 설정한다.
TPSQ_KEYGEN

시스템 키를 자동으로 생성하여 저장한다. 키(key)는 SQ_SYSKEY_SIZE 크기(keylenl = SQ_SYSKEY_SIZE)로 할당해야 한다. 성공적으로 수행했을 경우 키에 생성된 키 값이 저장된다.

반환값

반환값 설명

1

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

반환값	설명
1	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

오류

tmax_sq_put()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드	설명
[TPENOENT]	현 세션을 위한 SQ가 존재하지 않는다.
[TPEMATCH]	사용된 키 값이 이미 존재한다.
[TPELIMIT]	SQ 최대 개수를 초과했거나 SQ의 최대 키 개수를 초과하였다.

에러 코드

설명

[TPENOENT]

현 세션을 위한 SQ가 존재하지 않는다.

[TPEMATCH]

사용된 키 값이 이미 존재한다.

[TPELIMIT]

SQ 최대 개수를 초과했거나 SQ의 최대 키 개수를 초과하였다.

2.2. tmax_sq_get

데이터를 세션 큐에 저장하는 함수로 SQ에서 데이터를 가져오기 위해 키를 지정하면 해당 키의 데이터를 가져온다. 기본적으로 tmax_sq_get()을 수행하면 큐에서 데이터가 삭제된다. 데이터를 보존하려면 TPSQ_PEEK flags를 설정해야 한다.

프로토타입

#include <tmaxapi.h>
int tmax_sq_get(char *key, long keylenl, char **data, long *lenl, long flagsl)

파라미터

파라미터	설명
key	SQ에서 가져올 데이터를 위한 키 값을 저장할 버퍼이다.
keylenl	키 버퍼의 크기를 지정한다. (단위: Byte)
data	SQ에서 가져올 데이터 버퍼에 대한 포인터이다. 반드시 tpalloc()으로 할당된 버퍼에 대한 포인터이어야 한다.
lenl	SQ에서 가져온 데이터 버퍼의 크기가 저장된다. (단위: Byte)
flagsl	TPSQ_PEEK을 지정할 수 있다. 이 flags를 지정할 경우 데이터를 큐에서 삭제하지 않는다.

설명

key

SQ에서 가져올 데이터를 위한 키 값을 저장할 버퍼이다.

keylenl

키 버퍼의 크기를 지정한다. (단위: Byte)

data

SQ에서 가져올 데이터 버퍼에 대한 포인터이다. 반드시 tpalloc()으로 할당된 버퍼에 대한 포인터이어야 한다.

lenl

SQ에서 가져온 데이터 버퍼의 크기가 저장된다. (단위: Byte)

flagsl

TPSQ_PEEK을 지정할 수 있다. 이 flags를 지정할 경우 데이터를 큐에서 삭제하지 않는다.

반환값

반환값 설명

1

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_sq_get()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPENOENT]

현 세션을 위한 SQ가 존재하지 않는다.

[TPEMATCH]

지정한 키의 데이터가 존재하지 않는다.

반환값	설명
1	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPENOENT]	현 세션을 위한 SQ가 존재하지 않는다.
[TPEMATCH]	지정한 키의 데이터가 존재하지 않는다.

2.3. tmax_sq_count

현재 SQ에 저장된 데이터 개수를 반환하는 함수이다.

프로토타입

#include <tmaxapi.h>
int tmax_sq_count(void)

반환값

반환값 설명

0

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_sq_count()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPENOENT]

현 세션을 위한 SQ가 존재하지 않는다.

반환값	설명
0	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPENOENT]	현 세션을 위한 SQ가 존재하지 않는다.

2.4. tmax_sq_purge

SQ의 데이터를 삭제하기 위한 함수로 키를 지정할 경우 해당 키의 데이터를 삭제하고, 키를 지정하지 않으면 모든 데이터를 삭제한다.

프로토타입

#include <tmaxapi.h>
int tmax_sq_purge(char *key, long keylenl)

파라미터

파라미터	설명
key	SQ에서 삭제할 데이터를 위한 키 값을 저장할 버퍼이다. NULL일 경우 현 세션 SQ의 모든 데이터를 삭제한다.
keylenl	키 버퍼의 크기를 지정한다. (단위: Byte)

설명

key

SQ에서 삭제할 데이터를 위한 키 값을 저장할 버퍼이다. NULL일 경우 현 세션 SQ의 모든 데이터를 삭제한다.

keylenl

키 버퍼의 크기를 지정한다. (단위: Byte)

반환값

반환값 설명

삭제된 데이터의 개수

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_sq_purge()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPENOENT]

현 세션을 위한 SQ가 존재하지 않는다.

반환값	설명
삭제된 데이터의 개수	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPENOENT]	현 세션을 위한 SQ가 존재하지 않는다.

2.5. tmax_sq_keygen

시스템 키 생성 및 가져오기를 위한 함수로 시스템 키 사이즈는 SQ_SYSKEY_SIZE(16Byte)이다. 버퍼 크기는 시스템 키 사이즈보다 크거나 같게 할당해야 한다.

프로토타입

#include <tmaxapi.h>
int tmax_sq_keygen(char *key, long keylenl)

파라미터

파라미터	설명
key	생성된 시스템 키 값이 저장될 버퍼이다. 버퍼의 크기는 SQ_SYSKEY_SIZE(16Byte)보다 크게 할당해야 한다.
keylenl	키 버퍼의 크기를 지정한다. 반드시 SQ_SYSKEY_SIZE(16Byte)보다 커야 한다.

설명

key

생성된 시스템 키 값이 저장될 버퍼이다.

버퍼의 크기는 SQ_SYSKEY_SIZE(16Byte)보다 크게 할당해야 한다.

keylenl

키 버퍼의 크기를 지정한다. 반드시 SQ_SYSKEY_SIZE(16Byte)보다 커야 한다.

반환값

반환값 설명

1

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_sq_keygen()이 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPENOENT]

현 세션을 위한 SQ가 존재하지 않는다.

반환값	설명
1	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPENOENT]	현 세션을 위한 SQ가 존재하지 않는다.

2.6. tmax_sq_getkeylist

현 세션 SQ의 키 리스트를 가져오기 위한 함수이다. 키 리스트는 SQ_KEYLIST_T 타입의 핸들이 반환되며, 각 키에 대한 정보는 tmax_keylist_count(), tmax_keylist_getakey(), tmax_keylist_free() 함수를 통해서 확인할 수 있다.

키 리스트는 Byte 단위로 ASCII 코드값을 비교하여 낮은 값 우선으로 정렬된다. 키 값을 지정할 경우 해당 키 값보다 크거나 같은 키 리스트가 정렬되어 조회된다. 키 값을 NULL로 지정할 경우 전체 키 리스트가 조회된다.

프로토타입

#include <tmaxapi.h>
SQ_KEYLIST_T tmax_sq_getkeylist(char *key, long keylenl)

파라미터

파라미터 설명

key

키 값을 저장할 버퍼이다.

keylenl

키 버퍼의 크기를 지정한다. (단위: Byte)
반환값

반환값 설명

SQ_KEYLIST_T

함수 호출에 성공한 경우이다.

NULL

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_sq_getkeylist()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPENOENT]

현 세션을 위한 SQ가 존재하지 않는다.

[TPEMATCH]

지정한 키보다 크거나 같은 키가 존재하지 않는다.

파라미터	설명
key	키 값을 저장할 버퍼이다.
keylenl	키 버퍼의 크기를 지정한다. (단위: Byte)

반환값	설명
SQ_KEYLIST_T	함수 호출에 성공한 경우이다.
NULL	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPENOENT]	현 세션을 위한 SQ가 존재하지 않는다.
[TPEMATCH]	지정한 키보다 크거나 같은 키가 존재하지 않는다.

3. GQ API

3.1. tmax_gq_put

데이터를 GQ에 저장하는 함수로 키와 데이터 값을 전달한다. tmax_gq_keygen() 함수를 통해 생성된 시스템 키를 사용한다면 TPSQ_SYSKEY flags를 사용해야 한다. 시스템 키를 생성하여 저장하려면 TPSQ_KEYGEN flags를 사용해야 한다.

프로토타입

#include <tmaxapi.h>
int tmax_gq_put(char *key, long keylenl, char *data, long lenl, long flagsl)

파라미터

파라미터	설명
key	GQ에 저장할 데이터를 위한 키값을 저장할 버퍼이다.
keylenl	키 버퍼의 크기를 지정한다. (단위: Byte)
data	GQ에 저장할 데이터를 담고 있는 버퍼이다. 반드시 tpalloc()으로 할당된 버퍼에 대한 포인터이어야 한다.
lenl	GQ에 저장할 데이터 버퍼의 크기를 지정한다. (단위: Byte)
flagsl	TPSQ_UPDATE, TPSQ_SYSKEY, TPSQ_KEYGEN이 지정될 수 있다. 다음은 flagsl에 설정 가능한 값의 설명이다. TPSQ_UPDATE 키 값이 같을 경우 업데이트한다. 이 flags가 설정되어 있지 않으면 TPEMATCH 에러가 반환된다. TPSQ_SYSKEY 시스템 키를 사용할 경우 설정한다. TPSQ_KEYGEN 시스템 키를 자동으로 생성하여 저장한다. flags를 사용할 경우 key는 SQ_SYSKEY_SIZE 크기(keylenl = SQ_SYSKEY_SIZE)로 할당해야 한다. 성공적으로 수행할 경우 key에 생성된 키 값이 저장된다.

설명

key

GQ에 저장할 데이터를 위한 키값을 저장할 버퍼이다.

keylenl

키 버퍼의 크기를 지정한다. (단위: Byte)

data

GQ에 저장할 데이터를 담고 있는 버퍼이다. 반드시 tpalloc()으로 할당된 버퍼에 대한 포인터이어야 한다.

lenl

GQ에 저장할 데이터 버퍼의 크기를 지정한다. (단위: Byte)

flagsl

TPSQ_UPDATE, TPSQ_SYSKEY, TPSQ_KEYGEN이 지정될 수 있다.

다음은 flagsl에 설정 가능한 값의 설명이다.

TPSQ_UPDATE

키 값이 같을 경우 업데이트한다. 이 flags가 설정되어 있지 않으면 TPEMATCH 에러가 반환된다.
TPSQ_SYSKEY

시스템 키를 사용할 경우 설정한다.
TPSQ_KEYGEN

시스템 키를 자동으로 생성하여 저장한다. flags를 사용할 경우 key는 SQ_SYSKEY_SIZE 크기(keylenl = SQ_SYSKEY_SIZE)로 할당해야 한다. 성공적으로 수행할 경우 key에 생성된 키 값이 저장된다.

반환값

반환값 설명

1

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_gq_put()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPEMATCH]

사용된 키값이 이미 존재한다.

[TPELIMIT]

GQ의 최대 키 개수를 초과하였다.

반환값	설명
1	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPEMATCH]	사용된 키값이 이미 존재한다.
[TPELIMIT]	GQ의 최대 키 개수를 초과하였다.

3.2. tmax_gq_get

GQ에서 데이터를 가져오는 함수로 키를 지정하면 해당 키의 데이터를 가져온다. 기본적으로 tmax_gq_get() 을 수행하면 큐에서 데이터가 삭제된다. 데이터를 보존하려면 TPSQ_PEEK flags를 설정해야 한다.

프로토타입

#include <tmaxapi.h>
int tmax_gq_get(char *key, long keylenl, char **data, long *lenl, long flagsl)

파라미터

파라미터	설명
key	GQ에서 가져올 데이터를 위한 키값을 저장할 버퍼이다.
keylenl	키 버퍼의 크기를 지정한다. (단위: Byte)
data	GQ에서 가져올 데이터 버퍼에 대한 포인터이다. 반드시 tpalloc()로 할당된 버퍼에 대한 포인터이어야 한다.
lenl	GQ에서 가져온 데이터 버퍼의 크기가 저장된다. (단위: Byte)
flagsl	TPSQ_PEEK이 지정될 수 있다. 이 flags를 지정할 경우 데이터를 큐에서 삭제하지 않는다.

설명

key

GQ에서 가져올 데이터를 위한 키값을 저장할 버퍼이다.

keylenl

키 버퍼의 크기를 지정한다. (단위: Byte)

data

GQ에서 가져올 데이터 버퍼에 대한 포인터이다. 반드시 tpalloc()로 할당된 버퍼에 대한 포인터이어야 한다.

lenl

GQ에서 가져온 데이터 버퍼의 크기가 저장된다. (단위: Byte)

flagsl

TPSQ_PEEK이 지정될 수 있다. 이 flags를 지정할 경우 데이터를 큐에서 삭제하지 않는다.

반환값

반환값 설명

1

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_gq_get()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPEMATCH]

지정한 키의 데이터가 존재하지 않는다.

반환값	설명
1	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPEMATCH]	지정한 키의 데이터가 존재하지 않는다.

3.3. tmax_gq_count

GQ에 저장된 데이터의 개수를 반환한다.

프로토타입

#include <tmaxapi.h>
int tmax_gq_count (void)

반환값

반환값 설명

0

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_gq_count()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPENOENT]

현 세션을 위한 SQ가 존재하지 않는다.

반환값	설명
0	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPENOENT]	현 세션을 위한 SQ가 존재하지 않는다.

3.4. tmax_gq_purge

GQ의 데이터를 삭제하기 위한 함수로 키를 지정할 경우 해당 키의 데이터를 삭제하고 키를 지정하지 않을 경우 모든 데이터를 삭제한다.

프로토타입

#include <tmaxapi.h>
int tmax_gq_purge(char *key, long keylenl)

파라미터

파라미터	설명
key	GQ에서 삭제할 데이터를 위한 키값을 저장할 버퍼이다. NULL일 경우 GQ의 모든 데이터를 삭제한다.
keylenl	키 버퍼의 크기를 지정한다. (단위: Byte)

설명

key

GQ에서 삭제할 데이터를 위한 키값을 저장할 버퍼이다. NULL일 경우 GQ의 모든 데이터를 삭제한다.

keylenl

키 버퍼의 크기를 지정한다. (단위: Byte)

반환값

반환값 설명

삭제된 데이터의 개수

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_gq_purge()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPEINVAL]

잘못된 키를 입력한 경우이다.

[TPENOENT]

현 세션을 위한 SQ가 존재하지 않는다.

반환값	설명
삭제된 데이터의 개수	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPEINVAL]	잘못된 키를 입력한 경우이다.
[TPENOENT]	현 세션을 위한 SQ가 존재하지 않는다.

3.5. tmax_gq_keygen

시스템 키 생성 및 가져오기 위한 함수로 시스템 키 사이즈는 SQ_SYSKEY_SIZE(16Byte)이므로 이보다 버퍼 크기를 크거나 같게 할당해야 한다.

프로토타입

#include <tmaxapi.h>
int tmax_gq_keygen(char *key, long keylenl)

파라미터

파라미터	설명
key	생성된 시스템 키값이 저장될 버퍼이다. 버퍼의 크기는 SQ_SYSKEY_SIZE(16Byte)보다 크게 할당해야 한다.
keylenl	키 버퍼의 크기를 지정한다. 반드시 SQ_SYSKEY_SIZE(16Byte)보다 커야 한다.

설명

key

생성된 시스템 키값이 저장될 버퍼이다.

버퍼의 크기는 SQ_SYSKEY_SIZE(16Byte)보다 크게 할당해야 한다.

keylenl

키 버퍼의 크기를 지정한다. 반드시 SQ_SYSKEY_SIZE(16Byte)보다 커야 한다.

반환값

반환값 설명

1

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_gq_keygen()이 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPEINVAL]

잘못된 키를 입력한 경우이다.

반환값	설명
1	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPEINVAL]	잘못된 키를 입력한 경우이다.

3.6. tmax_gq_getkeylist

GQ의 키 리스트를 가져오기 위한 함수이다. 키 리스트는 SQ_KEYLIST_T 타입의 핸들이 반환되며, 각 키에 대한 정보는 tmax_keylist_count(), tmax_keylist_count(), tmax_keylist_free() 함수를 통해서 확인할 수 있다. 키 리스트는 Byte 단위로 ASCII 코드값을 비교하여 낮은 값 우선으로 정렬된다.

키 값을 지정할 경우 해당 키 값보다 크거나 같은 키 리스트가 정렬되어 조회된다. 키 값을 NULL로 지정할 경우 전체 키 리스트가 조회된다.

프로토타입

#include <tmaxapi.h>
SQ_KEYLIST_T tmax_gq_getkeylist(char *key, long keylenl)

파라미터

파라미터 설명

key

키 값을 저장할 버퍼이다.

keylenl

키 버퍼의 크기를 지정한다. (단위: Byte)
반환값

반환값 설명

SQ_KEYLIST_T

함수 호출에 성공한 경우이다.

NULL

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_gq_getkeylist()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPEMATCH]

지정한 키보다 크거나 같은 키가 존재하지 않는다.

파라미터	설명
key	키 값을 저장할 버퍼이다.
keylenl	키 버퍼의 크기를 지정한다. (단위: Byte)

반환값	설명
SQ_KEYLIST_T	함수 호출에 성공한 경우이다.
NULL	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPEMATCH]	지정한 키보다 크거나 같은 키가 존재하지 않는다.

4. 키 및 세션 조회 API

4.1. tmax_get_sessionid

현 세션의 ID를 반환하는 함수이다.

프로토타입

#include <tmaxapi.h>
int tmax_get_sessionid(void)

반환값

반환값 설명

-1이 아닌 값

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_get_sessionid()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPEPROTO]

세션이 이미 종료되었다.

반환값	설명
-1이 아닌 값	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPEPROTO]	세션이 이미 종료되었다.

4.2. tmax_keylist_count

keylist 핸들로부터 키 리스트의 개수를 반환한다.

프로토타입

#include <tmaxapi.h>
int tmax_keylist_count(SQ_KEYLIST_T keylist)

파라미터

파라미터 설명

keylist

tmax_sq_getkeylist() 또는 tmax_gri_getkeylist()로부터 전달받은 핸들이다.
반환값

반환값 설명

0

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_keylist_count()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPEBADDESC]

잘못된 keylist 핸들이다.

파라미터	설명
keylist	tmax_sq_getkeylist() 또는 tmax_gri_getkeylist()로부터 전달받은 핸들이다.

반환값	설명
0	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPEBADDESC]	잘못된 keylist 핸들이다.

4.3. tmax_keylist_getakey

keylist 핸들로부터 n번째 키 정보를 가져온다.

프로토타입

#include <tmaxapi.h>
int tmax_keylist_getakey(SQ_KEYLIST_T keylist, int nth, SQ_KEYINFO_T *keyinfo)

파라미터

파라미터	설명
keylist	tmax_sq_getkeylist() 또는 tmax_gq_getkeylist()로부터 전달받은 핸들이다.
nth	keylist 핸들로부터 n번째 키이다. n은 0에서부터 tmax_keylist_count() -1사이의 값이어야 한다.
keyinfo	n번째 키의 정보가 저장될 구조체로 자세한 설명은 표 이후의 내용을 참고한다.

설명

keylist

tmax_sq_getkeylist() 또는 tmax_gq_getkeylist()로부터 전달받은 핸들이다.

nth

keylist 핸들로부터 n번째 키이다. n은 0에서부터 tmax_keylist_count() -1사이의 값이어야 한다.

keyinfo

n번째 키의 정보가 저장될 구조체로 자세한 설명은 표 이후의 내용을 참고한다.

다음은 keyinfo에 대한 설명이다.

Structure keyinfo {
     long keylen
     long datalen
     time_t starttime
     char *key
};

멤버	설명
long keylen	키의 크기이다. (단위: Byte)
long datalen	데이터의 크기이다. (단위: Byte)
time_t starttime	데이터가 저장 또는 업데이트된 시간이다.
char *key	키 값을 담고 있는 버퍼이다.

멤버

설명

long keylen

키의 크기이다. (단위: Byte)

long datalen

데이터의 크기이다. (단위: Byte)

time_t starttime

데이터가 저장 또는 업데이트된 시간이다.

char *key

키 값을 담고 있는 버퍼이다.

반환값

반환값 설명

1

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_keylist_getakey()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPEBADDESC]

잘못된 keylist 핸들이다.

[TPELIMIT]

nth의 범위가 벗어났다.

반환값	설명
1	함수 호출에 성공한 경우이다.
-1	함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.

에러 코드	설명
[TPEBADDESC]	잘못된 keylist 핸들이다.
[TPELIMIT]	nth의 범위가 벗어났다.

4.4. tmax_keylist_free

keylist 핸들의 메모리나 기타 자원들을 해제한다.

프로토타입

#include <tmaxapi.h>
int tmax_keylist_free(SQ_KEYLIST_T keylist)

파라미터

파라미터 설명

keylist

tmax_sq_getkeylist() 또는 tmax_gq_getkeylist()로부터 전달받은 핸들이다.
반환값

반환값 설명

-1이 아닌 값

함수 호출에 성공한 경우이다.

-1

함수 호출에 실패한 경우이다. tperrno에 에러 코드가 설정된다.
오류

tmax_keylist_free()가 정상적으로 수행되지 않을 경우 tperrno에 다음 값 중 하나가 설정된다.

에러 코드 설명

[TPEBADDESC]

잘못된 keylist 핸들이다.