제3장 API

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

3.1. 개요

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

다음은 각 API별 목록이다.

참고

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

3.2. SQ API

3.2.1. tmax_sq_put

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

  • 프로토타입

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

  • 파라미터

    파라미터설명
    keySQ에 저장할 데이터를 위한 키 값을 저장할 버퍼이다.
    keylenl키 버퍼의 크기를 지정한다. (단위: Byte)
    dataSQ에 저장할 데이터를 담고 있는 버퍼로 반드시 tpalloc()으로 할당된 버퍼에 대한 포인터이어야 한다.
    lenlSQ에 저장할 데이터 버퍼의 크기를 지정한다. (단위: 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에 에러 코드가 설정된다.

  • 오류

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

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

3.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)

  • 파라미터

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

  • 반환값

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

  • 오류

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

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

3.2.3. tmax_sq_count

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

  • 프로토타입

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

  • 반환값

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

  • 오류

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

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

3.2.4. tmax_sq_purge

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

  • 프로토타입

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

  • 파라미터

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

  • 반환값

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

  • 오류

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

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

3.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)보다 커야 한다.

  • 반환값

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

  • 오류

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

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

3.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]지정한 키보다 크거나 같은 키가 존재하지 않는다.

3.3. GQ API

3.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)

  • 파라미터

    파라미터설명
    keyGQ에 저장할 데이터를 위한 키값을 저장할 버퍼이다.
    keylenl키 버퍼의 크기를 지정한다. (단위: Byte)
    dataGQ에 저장할 데이터를 담고 있는 버퍼이다. 반드시 tpalloc()으로 할당된 버퍼에 대한 포인터이어야 한다.
    lenlGQ에 저장할 데이터 버퍼의 크기를 지정한다. (단위: 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의 최대 키 개수를 초과하였다.

3.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)

  • 파라미터

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

  • 반환값

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

  • 오류

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

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

3.3.3. tmax_gq_count

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

  • 프로토타입

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

  • 반환값

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

  • 오류

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

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

3.3.4. tmax_gq_purge

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

  • 프로토타입

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

  • 파라미터

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

  • 반환값

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

  • 오류

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

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

3.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)보다 커야 한다.

  • 반환값

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

  • 오류

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

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

3.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]지정한 키보다 크거나 같은 키가 존재하지 않는다.

3.4. 키 및 세션 조회 API

3.4.1. tmax_get_sessionid

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

  • 프로토타입

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

  • 반환값

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

  • 오류

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

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

3.4.2. tmax_keylist_count

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

  • 프로토타입

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

  • 파라미터

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

  • 반환값

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

  • 오류

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

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

3.4.3. tmax_keylist_getakey

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

  • 프로토타입

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

  • 파라미터

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

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

    Structure keyinfo {
     long keylen
     long datalen
     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의 범위가 벗어났다.

3.4.4. tmax_keylist_free

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

  • 프로토타입

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

  • 파라미터

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

  • 반환값

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

  • 오류

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

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