API

This chapter describes how to use API to develop applications.

1. Overview

Tmax SQ system provides three types of APIs: APIs to use SQ, APIs to use GQ, and APIs related to keys and sessions. SQ APIs, which start with "tmax_sq_," and GQ APIs, which start with "tmax_gq_," execute in the same say.

The following is the list of APIs.

For more information about error codes in each API description, refer to Tmax Application Development Guide.

2. SQ APIs

2.1. tmax_sq_put

The tmax_sq_put function stores server data in SQ. Both the key and data value must be passed.

  • Prototype

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

  • Parameter

    Parameter Description

    key

    A buffer that stores the key of data being retrieved from SQ.

    keylenl

    The key buffer size. (Unit: byte)

    data

    A pointer to the data buffer to be retrieved from SQ. The buffer must be allocated by tpalloc().

    lenl

    The size of a data buffer retrieved from SQ (Unit: byte).

    flagsl

    One of the following flag values can be set:

    • TPSQ_UPDATE

      Updates data if the data’s key already exists in the SQ to which the data will be saved. If this flag is not specified, a TPEMATCH error will be returned.

    • TPSQ_SYSKEY

      Uses a system key created by a tmax_sq_keygen().

    • TPSQ_KEYGEN

      Generates and stores a system key. When TPSQ_KEYGEN is set, the key must be assigned based on SQ_SYSKEY_SIZE. When keylenl = SQ_SYSKEY_SIZE is set, the value created in the key is stored.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tmax_sq_put() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

    [TPEMATCH]

    The specified key value is already in use.

    [TPELIMIT]

    The maximum SQ count or the maximum key count was exceeded.

2.2. tmax_sq_get

The tmax_sq_get function retrieves data from SQ. Data can be retrieved by providing an associated key. By default, tmax_sq_get() deletes data in the queue. To preserve this data, the TPSQ_PEEK flag must be set.

  • Prototype

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

  • Parameter

    Parameter Description

    key

    The buffer that stores data from SQ.

    keylenl

    The key buffer size. (Unit: byte)

    data

    A pointer to a data buffer on SQ. The buffer must be allocated by tpalloc().

    lenl

    The size of a data buffer on SQ in bytes.

    flagsl

    Only TPSQ_PEEK is available. This flag prevents data from being deleted from the queue.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tmax_sq_get() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

    [TPEMATCH]

    No data matching the specified key was found.

2.3. tmax_sq_count

The tmax_sq_count function returns the number of data items currently stored in SQ.

  • Prototype

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

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Error

    If tmax_sq_count() fails, the following code is set in tperrno.

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

2.4. tmax_sq_purge

The tmax_sq_purge function deletes SQ data specified by a key. If no key is specified, all data in the SQ will be deleted.

  • Prototype

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

  • Parameter

    Parameter Description

    key

    A buffer that stores the key of data to be deleted from SQ. If NULL, all data in the current session’s SQ will be deleted.

    keylenl

    The key buffer size. (Unit: Byte)

  • Return Value

    Value Description

    Number of data items deleted

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tmax_sq_purge() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

2.5. tmax_sq_keygen

The tmax_sq_keygen function generates a system key and stores it in a buffer. The buffer size must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes), the system key size.

  • Prototype

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

  • Parameter

    Parameter Description

    key

    A buffer that stores a generated system key.

    Must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes).

    keylenl

    The key buffer size. Must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes).

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tmax_sq_keygen() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

2.6. tmax_sq_getkeylist

The tmax_sq_getkeylist function retrieves a list of keys for the current SQ. A key list is a SQ_KEYLIST_T type handle, and detailed information about each key can be obtained using tmax_keylist_count(), tmax_keylist_getakey(), and tmax_keylist_free(). A key list is sorted by the ASCII values of its bytes, in ascending order.

When a key value is specified, the function retrieves and sorts a list of keys greater than or equal to that value. If the key value is set to NULL, all keys are retrieved.

  • Prototype

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

  • Parameter

    Parameter Description

    key

    The buffer that stores key values.

    keylenl

    The size of the key buffer. (Unit: Byte)

  • Return Value

    Value Description

    SQ_KEYLIST_T

    The function call succeeded.

    NULL

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tmax_sq_getkeylist() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPENOENT]

    No SQ exists for the current session.

    [TPEMATCH]

    No key that is greater than or equal to the specified value was found.

3. GQ APIs

3.1. tmax_gq_put

The tmax_gq_put function enters data into GQ. Both the key value and data value must be passed. When using a system key generated by tmax_gq_keygen(), the TPSQ_SYSKEY flag must be set. To generate and store a system key, a TPSQ_KEYGEN flag must be set.

  • Prototype

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

  • Parameter

    Parameter Description

    key

    A buffer that stores the key of data being retrieved from GQ.

    keylenl

    The key buffer size. (Unit: byte)

    data

    A pointer to the data buffer to be retrieved from GQ. The buffer must be allocated by tpalloc().

    lenl

    The size of a data buffer retrieved from GQ (Unit: byte).

    flagsl

    One of the following flag values can be set:

    • TPSQ_UPDATE

      Updates data if the data key already exists in GQ to which the data will be saved. If this flag is not specified, a TPEMATCH error will be returned.

    • TPSQ_SYSKEY

      Uses a system key.

    • TPSQ_KEYGEN

      Generates and stores a system key. When TPSQ_KEYGEN is set, the key must be assigned based on SQ_SYSKEY_SIZE. When keylenl = SQ_SYSKEY_SIZE is set, the value created in the key is stored.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Error

    If tmax_gq_put() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEMATCH]

    The specified key value is already in use.

    [TPELIMIT]

    The maximum number of keys in GQ was exceeded.

3.2. tmax_gq_get

The tmax_gq_get function uses a key to retrieve data from GQ. By default, tmax_gq_get() deletes data retrieved in a queue. To preserve this data, a TPSQ_PEEK flag must be enabled.

  • Prototype

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

  • Parameter

    Parameter Description

    key

    A buffer that stores data from a GQ.

    keylenl

    A key buffer size. (Unit: byte)

    data

    A pointer to a data buffer on a GQ. The buffer must be allocated by a tpalloc().

    lenl

    The size of a data buffer on a GQ. (Unit: byte)

    flagsl

    Only TPSQ_PEEK is available. This flag prevents data from being deleted from a queue.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Error

    If tmax_gq_get() fails, the following code is set in tperrno.

    Error Code Description

    [TPEMATCH]

    No data is found for the specified key.

3.3. tmax_gq_count

The tmax_gq_count returns the number of data items stored in GQ.

  • Prototype

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

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Error

    If tmax_gq_count() fails, the following code is set in tperrno.

    Error Code Description

    [TPENOENT]

    No SQ for the current session exists.

3.4. tmax_gq_purge

The tmax_gq_purge function deletes GQ data specified by a key. If no key is specified, all data in the GQ will be deleted.

  • Prototype

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

  • Parameter

    Parameter Description

    key

    A buffer that stores the key of data to be deleted from GQ. If NULL, all data in the current session’s GQ will be deleted.

    keylenl

    The key buffer size. (Unit: Byte)

  • Return Value

    Value Description

    Number of data items deleted

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Error

    If tmax_gq_purge() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEINVAL]

    An invalid key was specified.

    [TPENOENT]

    No SQ exists for the current session.

3.5. tmax_gq_keygen

The tmax_gq_keygen function generates a system key and stores it in a buffer. The buffer size must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes), the system key size.

  • Prototype

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

  • Parameter

    Parameter Description

    key

    A buffer that stores a generated system key.

    Must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes).

    keylenl

    The key buffer size. Must be greater than or equal to SQ_SYSKEY_SIZE (16 bytes).

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Error

    If tmax_gq_keygen() faile, the following code is set in tperrno.

    Error Code Description

    [TPEINVAL]

    An invalid key was specified.

3.6. tmax_gq_getkeylist

The tmax_gq_getkeylist function retrieves a GQ key list. The key list is of type SQ_KEYLIST_T, and detailed key data can be accessed using functions such as tmax_keylist_count(), tmax_keylist_*(), and tmax_keylist_free(). The key list is sorted in ascending ASCII order by byte value.

When a key value is specified, the function queries the key list for entries greater than or equal to that value, returning the results in sorted order. If the key value is set to NULL, the entire key list is retrieved.

  • Prototype

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

  • Parameter

    Parameter Description

    key

    A buffer that stores keys.

    keylenl

    A key buffer size. (Unit: byte)

  • Return Value

    Value Description

    SQ_KEYLIST_T

    The function call succeeded.

    NULL

    The function call failed, and an error code is set in tperrno.

  • Error

    If tmax_gq_getkeylist() fails, the following code is set in tperrno.

    Error Code Description

    [TPEMATCH]

    No key greater than or equal to the specified value exists.

4. Key and Session APIs

4.1. tmax_get_sessionid

The tmax_get_sessionid function returns a current session ID.

  • Prototype

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

  • Return Value

    Value Description

    A value other than -1

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Error

    If tmax_get_sessionid() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEPROTO]

    The session was already ended.

4.2. tmax_keylist_count

The tmax_keylist_count function retrieves the key count from the keylist handle.

  • Prototype

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

  • Parameter

    Parameter Description

    keylist

    A handle obtained from tmax_sq_getkeylist() or tmax_gq_getkeylist().

  • Return Value

    Value Description

    0

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Error

    If tmax_keylist_count() fails, the following code is set in tperrno.

    Error Code Description

    [TPEBADDESC]

    The keylist handle is invalid.

4.3. tmax_keylist_getakey

The tmax_keylist_getakey function retrieves the n-th key information from the keylist handle.

  • Prototype

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

  • Parameter

    Parameter Description

    keylist

    A handle obtained from tmax_sq_getkeylist() or tmax_gq_getkeylist().

    nth

    The index of the n-th key retrieved from the keylist handle. The value of n must be between 0 and tmax_keylist_count() -1.

    keyinfo

    The structure that stores information about the n-th key. See the section below this table for details.

    The following shows content in the keyinfo structure.

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

    keylen

    The size of the key. (Unit: Byte)

    datalen

    The size of the data. (Unit: Byte)

    starttime

    The time when data was stored or updated.

    *key

    The buffer containing the key value.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Errors

    If tmax_keylist_getakey() fails, one of the following codes is set in tperrno.

    Error Code Description

    [TPEBADDESC]

    The keylist handle is invalid.

    [TPELIMIT]

    The value of n exceeds the limit.

4.4. tmax_keylist_free

The tmax_keylist_free function releases memory or other resources of the keylist handle.

  • Prototype

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

  • Parameter

    Parameter Description

    keylist

    A handle obtained from tmax_sq_getkeylist() or tmax_gq_getkeylist().

  • Return Value

    Value Description

    Other than -1

    The function call succeeded.

    -1

    The function call failed, and an error code is set in tperrno.

  • Error

    If tmax_keylist_free() fails, the following is set in tperrno.

    Error Code Description

    [TPEBADDESC]

    The keylist handle is invalid.