Native C/C++ API

C/C++ API следует практикам, используемым в драйверах других популярных СУБД.

Типовая сессия работы с СУБД имеет следующий сценарий:

  • соединение с сервером;
  • запрос на сервер;
  • получение ответа;
  • отключение от сервера.

При успешном соединении с сервером в вызывающий контекст возвращается дескриптор соединения, однозначно идентифицирующий клиентскую сессию. Этот дескриптор в дальнейшем используется во всех вызовах API.

При использовании API следует избегать использования «сырых» типов и числовых значений, не обернутых в константы и typedef-ы. На различных платформах определяемые в C/C API значения констант и макросов, а также нижележащих типов могут отличаться. Кроме того, они могут изменяться с изменением версий API.

nb_connect

NB_HANDLE nb_connect (
    const char * host,
    int sockport,
    const char * user,
    const char * password
);

Предпринимает попытку соединения с сервером NitrosBase.

Параметры:

  • host — имя узла сервера NitrosBase;
  • sockport — TCP-порт сервера NitrosBase;
  • user — пользователь сервера NitrosBase;
  • password — пароль пользователя сервера NitrosBase.

Возвращаемое значение:

  • в случае успеха — дескриптор соединения;
  • в случае неудачи — NB_INVALID_HANDLE.

В настоящее время NitrosBase не поддерживает аутентификацию. В параметрах user и password можно передавать любые значения, в том числе NULL.

nb_disconnect

NB_ERROR_T nb_disconnect (
    NB_HANDLE connection
);

Завершает соединение с сервером NitrosBase.

Параметры:

  • connection — дескриптор соединения с сервером.

Возвращаемое значение:

  • NB_SUCCESS в случае успеха;
  • код ошибки в случае неудачи.

nb_setoption

void nb_setoption (
    NB_HANDLE connection,
    NB_CONN_OPTIONS option,
    int value
);

Используется для настройки параметров соединения с сервером.

Параметры функции:

  • connection — дескриптор соединения;
  • option — параметр соединения, который следует настроить;
  • value — новое значение параметра соединения.

NB_CONN_OPTIONS — перечисление, которое содержит одно из следующих значений:

  • NB_OPT_ERROR_EXCEPTION1 - ошибка генерирует исключение, 0- ошибка не генерирует исключение (обработка с помощью функции nb_errno);
  • NB_OPT_DATETIME_MICROSECONDS — получение значений типа datetime с точностью до микросекунды (1) или с точностью до миллисекунды (0);
  • NB_OPT_AVGINTASDOUBLE1 - функция avg(intfield) возвращает double значение, 0 - функция avg(intfield) возвращает int значение (как MSSQL).

nb_errno

NB_ERROR_T nb_errno (
    NB_HANDLE connection
);

Возвращает код последней ошибки, ассоциированной с соединением.

Параметры:

  • connection — дескриптор соединения с сервером.

Возвращаемое значение:

  • NB_SUCCESS — успех;
  • NB_ERROR_UNKNOWN = (NB_ERROR | 0) — общая ошибка;
  • NB_ERROR_NOT_IMPLEMENTED = (NB_ERROR | 1) — функциональность не реализована;
  • NB_ERROR_UNEXPECTED = (NB_ERROR | 2) — неожиданный результат, при выполнении функции возникло непредусмотренное состояние;
  • NB_ERROR_ARGUMENTS = (NB_ERROR | 3) — некорректное сочетание значений аргументов функции;
  • NB_ERROR_TIMEOUT = (NB_ERROR | 4) — таймаут при выполнении функции;
  • NB_ERROR_NO_DATA = (NB_ERROR | 5) — нет данных при ответе на запрос.

nb_err_text

const char * nb_err_text (
    NB_HANDLE connection
);

Возвращает текст ошибки, ассоциированной с соединением.

Параметры:

  • connection — дескриптор соединения с сервером.

Возвращаемое значение — текст ошибки.

nb_execute_sql

NB_ERROR_T nb_execute_sql (
    NB_HANDLE connection,
    const char * query,
    size_t length
);

Выполняет SQL-запрос на сервере.

Параметры:

  • connection — дескриптор соединения с сервером;
  • query — текст запроса;
  • length — длина текста запроса.

Возвращаемое значение:

  • NB_SUCCESS в случае успеха;
  • код ошибки в случае неудачи.

Несмотря на название, функция может выполнять не только SQL-запросы, но также, к примеру, запросы на SPARQL и других поддерживаемых сервером языках запросов.

Параметр length используется в случае, если в тексте запроса встречаются бинарные данные (к примеру, символ \0).

nb_fetch_row

NB_ERROR_T nb_fetch_row (
    NB_HANDLE connection
);

Получение следующей записи из результирующего набора данных, который сервер вернул в ответ на запрос.

Параметры:

  • connection — дескриптор соединения с сервером.

Возвращаемое значение:

  • NB_SUCCESS в случае удачи;
  • код ошибки в случае неуспеха.

nb_field_count

int nb_field_count (
    NB_HANDLE connection
);

Возвращает число полей в последней записи, полученной с помощью nb_fetch_row .

Параметры:

  • connection — дескриптор соединения с сервером.

Возвращаемое значение:

  • число полей в случае успеха;
  • -1 в случае неудачи.

Число полей в результирующем наборе — не константная величина, и может отличаться от записи к записи. В графовой модели данных у различных узлов графа число полей может различаться.

nb_field_name

NB_ERROR_T nb_field_name (
    NB_HANDLE connection,
    int fieldnum, NBValue * name
);

Возвращает имя поля в записи, полученной последним вызовом nb_fetch_row.

Параметры:

  • connection — дескриптор соединения с сервером;
  • fieldnum — номер поля, начиная с 0;
  • name — указатель на структуру NBValue, в которую будет передан результат.

Структура NBValue определена следующим образом:

struct NBValue {
 NB_DATA_TYPE type;
 union {
     int intv;
     long long int64v;
     double dbl;
     struct {
         char *str;
         int len;
     };
 };
 bool null;
};

Возвращаемое значение:

  • в случае успеха возвращает NB_SUCCESS и заполняет структуру NBValue, на которую указывает указатель name;
  • при неудаче возвращает код ошибки.

nb_field_type

NB_DATA_TYPE nb_field_type ( NB_HANDLE connection, int fieldnum );

Возвращает тип поля в записи, полученной последним вызовом nb_fetch_row.

Параметры:

  • connection — дескриптор соединения с сервером;
  • fieldnum — номер поля, начиная с 0.

Возвращаемое значение — одно из следующих:

enum NB_DATA_TYPE {
 NB_DATA_NONE,
 NB_DATA_STRING,
 NB_DATA_INT,
 NB_DATA_INT64,
 NB_DATA_DOUBLE,
 NB_DATA_DATETIME,
 NB_DATA_BOOL,
};

Значение NB_DATA_NONE возвращается в случае ошибки.

nb_field_value

NB_ERROR_T nb_field_value (
    NB_HANDLE connection,
    int fieldnum,
    NBValue * v
);

Возвращает значение поля в записи, полученной последним вызовом nb_fetch_row.

Параметры:

  • connection — дескриптор соединения с сервером;
  • fieldnum — номер поля, начиная с 0;
  • v — указатель на структуру NBValue, в которую будет передан результат (см. описание функции nb_field_name).

Возвращаемое значение:

  • в случае успеха возвращает NB_SUCCESS и заполняет структуру NBValue, на которую указывает указатель v;
  • при неудаче возвращает код ошибки.

nb_get_tableslist

NB_ERROR_T nb_get_tableslist (
    NB_HANDLE connection,
);

Возвращает список таблиц (см. также описание псевдотаблицы INFORMATION_SCHEMA.TABLES).

Параметры:

  • connection — дескриптор соединения с сервером.

Возвращаемое значение:

  • NB_SUCCESS в случае удачи;
  • код ошибки в случае неуспеха.

После вызова этой функции следует вызывать nb_fetch_row и т. д., как если бы был выполнен обычный запрос с помощью nb_execute_sql. Результат выполнения запроса содержит два поля:

  • name — имя таблицы;
  • type — тип таблицы (2 — обычная таблица; 3 — ссылочная таблица, см. CREATE TABLE AS EDGE).

nb_get_tablesсhema

NB_ERROR_T nb_get_tableschema (
    NB_HANDLE connection,
    const char* table,
    size_t length
);

Возвращает список полей для указанной таблицы (см. также описание псевдотвблицы INFORMATION_SCHEMA.COLUMNS).

Параметры:

  • connection — дескриптор соединения с сервером;
  • table — название таблицы;
  • length — длина значения аргумента table.

После вызова этой функции следует вызывать nb_fetch_row и т. д., как если бы был выполнен обычный запрос с помощью nb_execute_sql. Результат выполнения запроса содержит пять полей:

  • name — имя поля;
  • type — тип поля:
    1 — string,
    2 — int,
    3 — bigint,
    4 — double,
    5 — datetime,
    6 — bool,
    7 — date,
    8 — является primary key либо foreign key (в текущей версии строка);
  • subtype — уточняет сведения в поле type:
    0 — обычное поле,
    1 — primary key,
    2 — foreign key;
  • linktable — название таблицы, на которую ссылается поле foreign key;
  • nullable.

nb_get_indexsсhema

NB_ERROR_T nb_get_indexschema( NB_HANDLE connection );

Возвращает JSON, содержащий информацию обо всех индексах в базе данных.

Параметры:

  • connection — дескриптор соединения с сервером;

После вызова этой функции следует вызывать nb_fetch_row и т. д., как если бы был выполнен обычный запрос с помощью nb_execute_sql.

Результат выполнения запроса содержит одну запись с одним полем, содержащим JSON.

Пример JSON

[
  {

    "name" : "p_age",
    "table" : "person",
    "fields" : [ "age" ]
  },
  {

    "name" : "p_city",
    "table" : "person",
    "fields" : [ "city" ]
  },
  {

    "name" : "c_model",
    "table" : "car",
    "fields" : [ "model" ]
  }
]

Создание клиентского приложения

При создании собственного приложения в Microsoft Visual Studio следует настроить каталоги библиотек и заголовочных файлов:

  • каталог nitrosbase/include необходимо добавить в список каталогов заголовочных файлов (Свойства проекта / Каталоги VC++ / Каталоги включения);
  • каталоги nitrosbase/lib и nitrosbase/bin необходимо добавить в список каталогов библиотек (Свойства проекта / Каталоги VC++ / Кталоги библиотек).

Возможны два варианта компоновки с клиентской библиотекой:

  • использование препроцессора: #pragma comment(lib, "nbclient.lib");
  • добавление библиотеки nbclient.lib в список дополнительных библиотек (в MS Visual Studio: Свойства проекта / Компоновщик / Ввод / Дополнительные зависимости).