# Создание DataMatrix 1.1 — C++ и C ABI

> Генерация символов DataMatrix ECC 200 по ГОСТ Р ИСО/МЭК 16022 с проверкой GS1 и профиля «Честного знака» — PNG и JPEG для печати маркировки.

Страница на сайте: https://libscanner.com/docs/datamatrix-generator/1.1/

## Обзор

Библиотека строит символы **DataMatrix ECC 200** по ГОСТ Р ИСО/МЭК 16022 (ISO/IEC 16022) и отдаёт их картинкой PNG или JPEG — в память или в файл. Поддерживаются все 24 квадратных размера, от 10×10 до 144×144, шесть схем кодирования (ASCII, C40, Text, X12, EDIFACT, Base256) и опция GS1 с проверкой строки по GS1 General Specifications и профилю «Честного знака».

Каждый собранный символ библиотека читает обратно сама (самопроверка): рамки, кодовые слова, синдромы Рида–Соломона, разбор схем. Символ, который не прочитался, наружу не отдаётся.

Публичный интерфейс — на C++20, заголовки в `include/dmgen/`. Публичный API не бросает исключений: всё, что может не получиться, возвращает `Result<T>`. Для других языков есть плоский C ABI (`dmgen_c`) — годится для P/Invoke, JNA, cgo и ctypes.

> **Платформы.** Windows x86-64 и Linux x86-64, ARM64 и ARMv7 — библиотека собирается и проверяется в том числе для одноплатных компьютеров вроде Raspberry Pi. Сторонний код встроен в поставку, внешних зависимостей нет.

## Подключение

Библиотека приходит уже собранной — собирается только ваша программа. Подключить её можно двумя способами: **статически** — C++ API из `libdmgen.a` входит в вашу программу целиком, или **динамически** — через библиотеку `dmgen_c` с плоским интерфейсом на C (C ABI). Состав поставки:

**Windows:**

```
include\dmgen\{Dmgen,Encoder,Gs1,Image,License,Options,Result,Symbol,Version}.h   C++ API
include\dmgen\dmgen_c.h                                                                C ABI
lib\libdmgen.a               статическая библиотека C++
lib\pkgconfig\dmgen.pc
bin\dmgen_c.dll              библиотека C ABI
lib\dmgen_c.dll.a            её библиотека импорта (MinGW)
bin\dmgen.exe                утилита командной строки
share\doc\dmgen\licenses\     лицензии сторонних библиотек
```

**Linux:**

```
include/dmgen/{Dmgen,Encoder,Gs1,Image,License,Options,Result,Symbol,Version}.h   C++ API
include/dmgen/dmgen_c.h                                                              C ABI
lib/libdmgen.a                статическая библиотека C++
lib/pkgconfig/dmgen.pc
lib/libdmgen_c.so -> libdmgen_c.so.1 -> libdmgen_c.so.1.1.1   библиотека C ABI
bin/dmgen                     утилита командной строки
share/doc/dmgen/licenses/     лицензии сторонних библиотек
```

Поставки `linux` (x86-64), `linux-arm64` и `linux-armhf` одинаковы по составу.

| Ваша программа | Что брать |
| --- | --- |
| C++, собирается MinGW-w64 GCC (Windows) или GCC (Linux) | Статическая линковка — C++ API, `libdmgen.a` |
| MSVC или другой компилятор; другой язык (C, C#, Java, Go…); обновление библиотеки без пересборки программы | Динамическая линковка — C ABI, `dmgen_c` |
| Python | Колесо из «Загрузок» — [документация Python](https://libscanner.com/docs/datamatrix-generator/1.1/python.md) |

### Статическая линковка — C++ API

`libdmgen.a` входит в вашу программу целиком: рядом с ней ничего класть не нужно, кроме файла ключа `dmgen.key` (см. «Лицензия»). Нужен компилятор **C++20** с той же стандартной библиотекой C++, что и у поставки (той же или более новой версии).

**Windows:**

`libdmgen.a` собрана MinGW-w64 GCC — MSVC её не слинкует, нужен тот же тулчейн: [MSYS2](https://www.msys2.org/), консоль **MINGW64** (не UCRT64), пакеты `pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-pkgconf`. Из MSVC — динамически, через dmgen_c. Строка линковки — из `dmgen.pc`; пути в нём считаются от места самого файла, так что каталог распаковки может быть любым:

```bash
$env:PKG_CONFIG_PATH = "C:\куда\распакован\lib\pkgconfig"
pkg-config --static --cflags --libs dmgen
```

Системные `winhttp`, `crypt32`, `shell32` и `advapi32` (проверка лицензии) уже прописаны в пакете.

**Linux:**

Поставка собрана GCC 12 (Debian 12): нужен GCC 12 или новее. Строка линковки — из `dmgen.pc`, каталог распаковки может быть любым:

```bash
PKG_CONFIG_PATH=/куда/распакован/lib/pkgconfig pkg-config --static --cflags --libs dmgen
```

Нужны `-pthread -ldl` — они уже в пакете.

В meson — зависимость по имени пакета:

```cpp
dmgen_dep = dependency('dmgen', required: true, static: true)
executable('мояпрограмма', 'main.cpp', dependencies: [dmgen_dep],
  link_args: ['-static'])   # Windows: рантайм MinGW внутрь программы
```

Под Windows `-static` вкомпоновывает в программу и рантайм компилятора: без него она потребует рядом `libstdc++-6.dll`, `libgcc_s_seh-1.dll` и `libwinpthread-1.dll` из MSYS2. Под Linux он не нужен.

### Динамическая линковка — C ABI

`dmgen_c` — та же библиотека за плоским интерфейсом на C (заголовок `dmgen/dmgen_c.h`, подробно — C ABI). Рантайм компилятора вкомпонован в неё статически, поэтому она не зависит ни от компилятора вызывающего, ни от его стандартной библиотеки C++. Отдельного `.pc` для неё нет — пути указываются напрямую.

**Windows:**

**MinGW-w64 GCC** — через библиотеку импорта `lib\dmgen_c.dll.a`:

```bash
gcc main.c -o мояпрограмма.exe -I C:/куда/распакован/include -L C:/куда/распакован/lib -ldmgen_c
```

**MSVC** — файла `.lib` в поставке нет, его делают из самой DLL. В консоли MSYS2 — описание экспорта:

```bash
gendef dmgen_c.dll        # пакет mingw-w64-x86_64-tools; пишет dmgen_c.def
```

затем в Developer Command Prompt for VS (x64) — библиотека импорта и сборка:

```bash
lib /def:dmgen_c.def /machine:x64 /out:dmgen_c.lib
cl /I C:\куда\распакован\include main.c dmgen_c.lib
```

При запуске `dmgen_c.dll` должна лежать рядом с вашим `.exe` (или в каталоге из `PATH`), а файл ключа `dmgen.key` — рядом с `dmgen_c.dll`.

**Linux:**

```bash
cc main.c -o мояпрограмма -I/куда/распакован/include -L/куда/распакован/lib -ldmgen_c
```

При запуске загрузчик ищет `libdmgen_c.so.1`: либо через `LD_LIBRARY_PATH`, либо положите её рядом с программой и пропишите путь поиска при линковке:

```bash
LD_LIBRARY_PATH=/куда/распакован/lib ./мояпрограмма

# или: библиотека рядом с программой
cc main.c -o мояпрограмма -I/куда/распакован/include -L/куда/распакован/lib -ldmgen_c -Wl,-rpath,'$ORIGIN'
cp -a /куда/распакован/lib/libdmgen_c.so.1* .
```

Файл ключа `dmgen.key` — рядом с `libdmgen_c.so`.

Колесо Python — обёртка как раз над `dmgen_c`, библиотека лежит внутри пакета: [документация Python](https://libscanner.com/docs/datamatrix-generator/1.1/python.md).

## Быстрый старт

Код «Честного знака» → файл PNG. Всё, что нужно, — один заголовок:

```cpp
#include <dmgen/Dmgen.h>
#include <iostream>

int main() {
    dmgen::EncodeOptions o;
    o.gs1 = dmgen::Gs1Mode::ChestnyZnak;          // проверка и FNC1 первым словом

    auto sym = dmgen::encode("(01)04601234567893(21)5Abc12Xyz!-(93)dGVz", o);
    if (!sym) {
        std::cerr << sym.error().message << "\n";   // на языке сообщений («Ошибки»)
        return 1;
    }

    dmgen::RenderOptions r;                        // 8 px на модуль, свободная зона 2
    auto saved = dmgen::save(dmgen::render(sym->modules, r), "code.png", dmgen::ImageFormat::Png);
    return saved ? 0 : 1;
}
```

Картинка в память — `dmgen::toPng(image)` или `dmgen::toJpeg(image)`, обе возвращают `Result<std::vector<uint8_t>>`.

## Кодирование

```cpp
Result<Symbol> encode(std::string_view data, const EncodeOptions& options = {});
```

Байты 128–255 кодируются через Upper Shift. Текст не перекодируется: строку UTF-8 символ хранит как UTF-8.

### EncodeOptions

| Поле | По умолчанию | Смысл |
| --- | --- | --- |
| `side` | `0` | Сторона символа: 0 — наименьший подходящий, иначе 10, 12, 14, 16, 18, 20, 22, 24, 26, 32, 36, 40, 44, 48, 52, 64, 72, 80, 88, 96, 104, 120, 132, 144. Не из списка — `InvalidArgument`, не помещается — `SizeTooSmall`. |
| `encodation` | `Auto` | `Auto` — схемы выбирает предпросмотр приложения P ГОСТ; `Minimal` — кратчайший поток (дольше считается); либо одна схема: `Ascii`, `C40`, `Text`, `X12`, `Edifact`, `Base256`. |
| `gs1` | `Off` | `Off`, `Gs1`, `ChestnyZnak`. Строка проверяется до кодирования; нарушение — `Gs1Invalid`. |
| `separator` | `Gs29` | Разделитель групп: `Gs29` — байт GS, как в «Честном знаке»; `Fnc1` — кодовое слово 232 (только в режиме `Gs1`). |
| `gs1Input` | `Auto` | `Raw` — разделитель байтом 0x1D или записью `<GS>`, `{GS}`, `\x1D`; `Bracketed` — `(01)…(21)…`, разделители расставятся сами; `Auto` — по «(» в начале. |
| `verify` | `true` | Самопроверка: собранный символ читается обратно и сравнивается со входом. |

### Symbol

`info` — выбранный размер (`SymbolInfo`), `modules` — матрица модулей без свободной зоны (`BitMatrix`, 1 — тёмный), `codewords` — кодовые слова в порядке размещения, `segments` — какая схема на каком участке, `text` — строка, которую вернёт ридер. Таблица размеров — `dmgen::squareSizes()`.

## GS1 и «Честный знак»

```cpp
auto rep = dmgen::gs1::validate("(01)04601234567894(21)ABC", dmgen::Gs1Mode::ChestnyZnak);
for (const auto& i : rep.issues)
    std::cout << (i.warning ? "предупреждение: " : "ошибка: ") << i.message << "\n";
// ошибка: AI (01) GTIN: контрольная цифра 4, должна быть 3
// ошибка: «Честный знак»: нет кода проверки — нужен 93 или пара 91 и 92
```

Проверяются известность AI, длины и наборы знаков, контрольные цифры GTIN/SSCC/GLN, даты, обязательные разделители после AI без предопределённой длины и повторы AI. Профиль «Честного знака»: 01 первым, 21 вторым, код проверки 93 (4 знака) или 91 (4) + 92 (44 или 88).

`Report::normalized` — строка ровно в том виде, в каком её вернёт ридер (с байтом GS). Проверка GS1 лицензии не требует.

## Картинка

| Функция | Что делает |
| --- | --- |
| `render(modules, RenderOptions)` | Растр Gray8: `modulePx` (8), `quietZone` (2; ГОСТ — не меньше 1), `invert`, `dark`/`light`, `dpi`. |
| `RenderOptions::fromMm(мм, dpi)` | Модуль в миллиметрах при разрешении печати; DPI пишется в файл (pHYs, JFIF). |
| `RenderOptions::jpegFriendly()` | Модуль кратен 8 px: блоки 8×8 JPEG однотонные, звона на краях нет. |
| `toPng`, `toJpeg`, `save` | PNG (рекомендуется) или JPEG в память или в файл; путь — `std::filesystem::path`, Юникод на Windows работает. Качество JPEG ниже 90 для штрихкода не рекомендуется. |

```cpp
auto r = dmgen::RenderOptions::fromMm(0.5, 300);   // модуль 0,5 мм при 300 dpi
dmgen::save(dmgen::render(sym->modules, r), "label.png", dmgen::ImageFormat::Png);
```

## Ошибки

`Result<T>` — значение или `Error` с полями `code` и `message` (UTF-8, на языке сообщений, см. ниже). Кому удобнее исключения — `value()` бросает `std::runtime_error` с текстом ошибки.

**Язык сообщений.** Сообщения — на русском или английском: переменная окружения `LIBSCANNER_LANG` (`ru` или `en`), иначе язык системы — русская система даёт русский, любая другая (и локаль `C` в контейнере) — английский. Из кода — `dmgen::setMessageLanguage("en")` (`dmgen/Language.h`, на весь процесс); `dmgen::messageLanguage()` возвращает текущий. Утилита принимает `--lang ru|en`. Коды ошибок не переводятся.

| ErrorCode | Смысл |
| --- | --- |
| `InvalidArgument` | Неверная опция: размер не из таблицы, пустые данные… |
| `DataTooLong` | Данные не помещаются даже в 144×144 |
| `SizeTooSmall` | Данные не помещаются в явно заданный размер |
| `UnencodableChar` | Знак нельзя закодировать выбранной схемой |
| `Gs1Invalid` | Строка не прошла проверку GS1 (подробности — `gs1::validate`) |
| `IoError` | Не удалось записать файл или изображение |
| `InternalVerifyFailed` | Самопроверка не прочитала собранный символ — ошибка dmgen |
| `Unlicensed` | Пробный период кончился, лицензии нет |

## C ABI

Библиотека `dmgen_c.dll` / `libdmgen_c.so`, заголовок `dmgen_c.h`, экспортируются только `dmgen_*`. Только C-типы фиксированного размера, опции со `struct_size`, память освобождает `dmgen_free`; есть вариант с буфером вызывающего — `dmgen_make_image_into`.

```cpp
dmgen_options o; dmgen_error e; uint8_t* png; size_t len;
dmgen_options_init(&o);
o.gs1 = DMGEN_GS1_CHESTNY_ZNAK;
if (dmgen_make_image((const uint8_t*)data, n, &o, DMGEN_FORMAT_PNG, &png, &len, &e) == DMGEN_OK) {
    /* … */
    dmgen_free(png);
}
```

`dmgen_options_init` заполняет умолчания и сам ставит `struct_size` — вызовите её первой, потом меняйте поля. В строковом литерале C разделитель — отдельным литералом: `"…LM" "\x1D" "93ABCD"`, иначе в `"\x1D93"` компилятор заберёт в одну escape-последовательность все шестнадцатеричные цифры. При ошибке в `error` — код и сообщение в UTF-8 на языке сообщений («Ошибки»). В Linux у библиотеки SONAME `libdmgen_c.so.1` (файл `libdmgen_c.so.1.1.1`); файла `.pc` для `dmgen_c` нет — укажите `-I…/include -L…/lib -ldmgen_c` сами. Файл ключа `dmgen.key` — рядом с библиотекой или рядом с программой (раздел «Лицензия»).

### Справочник

Все объявления `dmgen_c.h` (ABI 1), с комментариями самого заголовка (они по-английски):

```cpp
#define DMGEN_ABI_VERSION 1

/* Return codes: 0 is success, the rest match dmgen::ErrorCode. */
typedef int32_t dmgen_status;
enum {
    DMGEN_OK                     = 0,
    DMGEN_E_INVALID_ARGUMENT     = 1,
    DMGEN_E_DATA_TOO_LONG        = 2,
    DMGEN_E_SIZE_TOO_SMALL       = 3,
    DMGEN_E_UNENCODABLE_CHAR     = 4,
    DMGEN_E_GS1_INVALID          = 5,
    DMGEN_E_IO                   = 6,
    DMGEN_E_INTERNAL_VERIFY      = 7,
    DMGEN_E_UNLICENSED           = 8,   /* trial period over and no license */
    DMGEN_E_BUFFER_TOO_SMALL     = 100  /* dmgen_make_image_into only */
};

enum { DMGEN_FORMAT_PNG = 0, DMGEN_FORMAT_JPEG = 1 };
enum { DMGEN_GS1_OFF = 0, DMGEN_GS1_GS1 = 1, DMGEN_GS1_CHESTNY_ZNAK = 2 };
enum { DMGEN_SEPARATOR_GS = 0, DMGEN_SEPARATOR_FNC1 = 1 };
enum { DMGEN_INPUT_AUTO = 0, DMGEN_INPUT_RAW = 1, DMGEN_INPUT_BRACKETED = 2 };
enum {
    DMGEN_SCHEME_AUTO = 0, DMGEN_SCHEME_ASCII, DMGEN_SCHEME_C40, DMGEN_SCHEME_TEXT,
    DMGEN_SCHEME_X12, DMGEN_SCHEME_EDIFACT, DMGEN_SCHEME_BASE256, DMGEN_SCHEME_MINIMAL
};

/* Encoding and rendering options. Initialize with dmgen_options_init. */
typedef struct dmgen_options {
    uint32_t struct_size;   /* sizeof(dmgen_options) as compiled by the caller */
    int32_t  gs1;           /* DMGEN_GS1_* */
    int32_t  separator;     /* DMGEN_SEPARATOR_* */
    int32_t  gs1_input;     /* DMGEN_INPUT_* */
    int32_t  scheme;        /* DMGEN_SCHEME_* */
    int32_t  side;          /* 0 — smallest that fits, otherwise a standard side 10…144 */
    int32_t  verify;        /* 1 — self-check (default) */
    int32_t  module_px;     /* pixels per module, default 8 */
    int32_t  quiet_zone;    /* modules, default 2 */
    int32_t  invert;        /* 0/1 */
    int32_t  dark;          /* 0…255, default 0 */
    int32_t  light;         /* 0…255, default 255 */
    int32_t  jpeg_quality;  /* 1…100, default 100 */
    int32_t  reserved;      /* alignment, 0 */
    double   dpi;           /* 0 — not written to the file */
} dmgen_options;

typedef struct dmgen_error {
    int32_t code;           /* dmgen_status */
    char    message[512];   /* UTF-8, null-terminated */
} dmgen_error;

typedef struct dmgen_gs1_element {
    char   ai[8];           /* null-terminated */
    char*  value;           /* UTF-8, null-terminated */
    size_t value_len;
} dmgen_gs1_element;

typedef struct dmgen_gs1_issue {
    int32_t code;           /* dmgen::gs1::IssueCode */
    int32_t warning;        /* 1 — warning */
    int32_t position;
    char    ai[8];
    char    message[256];
} dmgen_gs1_issue;

typedef struct dmgen_gs1_report {
    int32_t            ok;
    int32_t            element_count;
    dmgen_gs1_element* elements;
    int32_t            issue_count;
    dmgen_gs1_issue*   issues;
    char*              normalized;      /* with 0x1D bytes, as a reader returns it */
    size_t             normalized_len;
} dmgen_gs1_report;

uint32_t    dmgen_abi_version(void);
const char* dmgen_version_string(void);

void dmgen_options_init(dmgen_options* options);

/* Data → PNG or JPEG in memory. Free *out with dmgen_free. */
dmgen_status dmgen_make_image(const uint8_t* data, size_t len,
                                        const dmgen_options* options, int32_t format,
                                        uint8_t** out, size_t* out_len, dmgen_error* error);

/* Same, into a caller-provided buffer. If cap is too small, returns
 * DMGEN_E_BUFFER_TOO_SMALL and sets *needed to the required size; buf may be
 * NULL when cap = 0. */
dmgen_status dmgen_make_image_into(const uint8_t* data, size_t len,
                                             const dmgen_options* options, int32_t format,
                                             uint8_t* buf, size_t cap, size_t* needed,
                                             dmgen_error* error);

/* Data → file (UTF-8 path; Unicode works on Windows). */
dmgen_status dmgen_save_image(const uint8_t* data, size_t len,
                                        const dmgen_options* options, int32_t format,
                                        const char* path_utf8, dmgen_error* error);

/* Data → side×side module matrix (1 is dark, rows top to bottom).
 * Free *modules with dmgen_free. */
dmgen_status dmgen_encode_matrix(const uint8_t* data, size_t len,
                                           const dmgen_options* options,
                                           uint8_t** modules, int32_t* side, dmgen_error* error);

/* GS1 validation. Free *report with dmgen_gs1_report_free. The return code
 * tells whether the call itself succeeded; whether the string is valid is the
 * report's ok field. */
dmgen_status dmgen_gs1_validate(const uint8_t* data, size_t len, int32_t mode,
                                          int32_t input, dmgen_gs1_report** report,
                                          dmgen_error* error);
void dmgen_gs1_report_free(dmgen_gs1_report* report);

/* Sides of the 24 standard square sizes in increasing order; returns their
 * count (24) and writes at most cap values. */
int32_t dmgen_symbol_sizes(int32_t* sides, int32_t cap);

void dmgen_free(void* p);

/* ── License (dmgen/License.h) ──────────────────────────────────────────────
 *
 * Symbol-producing functions return DMGEN_E_UNLICENSED while there is neither
 * a trial period nor a license. The primary activation method is a dmgen.key
 * file containing the key, placed next to dmgen_c.dll / libdmgen_c.so: no
 * calls are needed.
 *
 * Responses are UTF-8 JSON, the same as "dmgen --license ... --json":
 *   status     {"state","can_encode","valid_until","refresh_after",
 *               "offline_until","days_left","license_id","activation_id",
 *               "offline_mode","clock_rollback","message"}
 *   operation  {"ok","error","message","status":{...status...}}
 * state is one of trial, active, refresh_due, trial_expired, expired,
 * network_required, wrong_machine, invalid. Free the string with dmgen_free;
 * NULL means an internal error or NULL in a required argument. Paths are
 * UTF-8. Network functions wait for the server at most timeout_ms. */

/* Call before the first network call and the first encoding; optional.
 * server_url, app_version — NULL or "" for the default; timeout_ms <= 0 —
 * 15000; auto_check — daily background check with the server (1 — on). */
void  dmgen_license_configure(const char* server_url, const char* app_version,
                                        int32_t timeout_ms, int32_t auto_check);
char* dmgen_license_status_json(void);
char* dmgen_license_activate_json(const char* key);
char* dmgen_license_refresh_json(void);
char* dmgen_license_deactivate_json(const char* reason);     /* reason may be NULL */
char* dmgen_license_deactivate_to_file_json(const char* path_utf8, const char* reason);
char* dmgen_license_write_activation_request_json(const char* path_utf8);
char* dmgen_license_import_license_file_json(const char* path_utf8);
/* {"fingerprint":"<hex>"} */
char* dmgen_license_fingerprint_json(void);
```

## Версия библиотеки

`DMGEN_VERSION_STRING` — версия заголовков, `dmgen::versionString()` — версия, с которой собрана библиотека. По расхождению видно, что заголовки и `.a` от разных сборок.

## Лицензия

Библиотека кодирует, пока идёт пробный период (месяц с первого запуска на машине, без сети и регистрации) или действует лицензия. Иначе `encode()` отвечает `ErrorCode::Unlicensed`. Проверка GS1 и рисование готовой матрицы лицензии не требуют. Лицензия привязана к оборудованию (материнская плата, процессор, системный диск), а не к установке ОС; пробный период и лицензия не зависят от библиотеки распознавания на той же машине.

```cpp
#include <dmgen/License.h>

dmgen::LicenseStatus s = dmgen::license::status();
if (!s.canEncode()) std::cerr << s.message;          // «Пробный период закончился. Нужна лицензия»

dmgen::license::activate("XXXXX-XXXXX-XXXXX-XXXXX-XXXXX");   // онлайн
dmgen::license::writeActivationRequest("request.json");        // офлайн: в личный кабинет …
dmgen::license::importLicenseFile("license.lic");              // … и обратно
dmgen::license::deactivate();                                   // переезд на другую машину
```

`deactivate()` сдаёт место распиской этой машины. Каждый ответ сервера лицензий привязан к своему запросу: библиотека отправляет случайное одноразовое число, сервер возвращает его в подписанном ответе, и записанный раньше ответ повторно не примется. Расписка тоже одноразовая — в ней номер из последнего полученного от сервера ответа, поэтому расписку из восстановленной копии старого состояния машины сервер не примет; секрет для её подписи сервер выдаёт только при первой активации машины. У лицензий с полной автономией (`full`) сдача места расходует лимит переносов; когда он исчерпан, перенос делает поддержка. Самостоятельно освободить место по лицензии можно не больше двух раз за 30 дней в режиме limited и не больше одного раза — в extended; дальше перенос делает поддержка.

> **Основной способ — файл dmgen.key.** Положите текстовый файл `dmgen.key` с ключом рядом с `dmgen_c.dll` / `libdmgen_c.so` или с программой. При первом обращении к библиотеке ключ уйдёт на сервер — один раз; дальше лицензия раз в сутки сама сверяется с сервером в фоновом потоке, кодирование сети не ждёт никогда.

### Состояния

| LicenseState | Кодирует | Смысл |
| --- | --- | --- |
| `Trial` | да | Идёт пробный период |
| `Active` | да | Лицензия действует |
| `RefreshDue` | да | Давно не было связи с сервером; библиотека сама пробует раз в час |
| `TrialExpired` | нет | Пробный период кончился — нужна лицензия |
| `Expired` | нет | Оплаченный срок кончился; продление в кабинете подхватится само |
| `NetworkRequired` | нет | Срок работы без связи вышел — нужна связь с сервером |
| `WrongMachine` | нет | Лицензия выдана другой машине |
| `Invalid` | нет | Запись лицензии не проходит проверку подписи |

Режим автономии задаёт тариф: `limited` — 7 дней без связи и ещё 7 после предупреждения, `extended` — 30 + 90, `full` — в сеть не нужно никогда.

### Контейнеры: Docker, Kubernetes

С версии 1.1 в контейнере библиотека работает по лицензии «на экземпляры»: ключ передаётся переменной окружения `DMGEN_LICENSE_KEY` или секретом — файлом`/run/secrets/dmgen.key` (сначала проверяется переменная, затем секрет, затем файл ключа рядом с библиотекой и программой). Активировать и отвязывать ничего не нужно: экземпляр занимает место при старте, раз в 30 минут в фоне отчитывается серверу лицензий и освобождает место при выходе программы. Пробного периода без ключа в контейнере нет — пробный ключ для контейнеров (2 экземпляра на 30 дней) выдаётся в личном кабинете. Ключ лицензии «на машины» в контейнере не активируется.[Подробнее о лицензии на экземпляры](https://libscanner.com/articles/licenziya-docker-kubernetes/).

Каждый процесс — отдельный экземпляр. Если программа запускает рабочие процессы через fork уже после загрузки библиотеки (gunicorn с `--preload`, `multiprocessing`, uWSGI без `lazy-apps`), каждый рабочий процесс занимает своё место при первом построении кода, а главный процесс, который сам кодов не строит, освобождает своё в течение 30 минут. Мест нужно столько, сколько процессов работает одновременно. Процесс, завершённый без штатного выхода (`os._exit`, `kill -9`), освобождает место через час.

Лицензия на экземпляры файлом не активируется: экземпляру нужна связь с сервером лицензий, без неё он работает 7 дней с последнего отчёта. Обычную машину без интернета (лицензия на машины) можно активировать файлом на весь оплаченный срок: при загрузке запроса в личном кабинете отметьте «Машина без интернета — работать весь срок без связи».

## Командная строка

```bash
dmgen "0104601234567893215Abc12Xyz!-<GS>93dGVz" --gs1=cz -o code.png
dmgen --check-gs1 --gs1=cz "(01)04601234567893(21)5Abc12Xyz!-(93)dGVz"
dmgen --all-sizes "Hello" --out-dir sizes/
dmgen --batch codes.txt --out-dir out/ --gs1=cz --mm=0.5 --dpi=300

dmgen --license status                # состояние, срок, автономия
dmgen --license activate <ключ>
dmgen --license deactivate            # переезд на другую машину
```

Ключи: `--size=`, `--scheme=`, `--separator=`, `--input=`, `--px=`, `--quiet=`, `--mm=` с `--dpi=`, `--invert`, `--jpeg-friendly`, `--quality=`. Без лицензии утилита завершается с кодом 4.
