Обзор
Библиотека строит символы 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). Состав поставки:
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\ лицензии сторонних библиотек| Ваша программа | Что брать |
|---|---|
| C++, собирается MinGW-w64 GCC (Windows) или GCC (Linux) | Статическая линковка — C++ API, libdmgen.a |
| MSVC или другой компилятор; другой язык (C, C#, Java, Go…); обновление библиотеки без пересборки программы | Динамическая линковка — C ABI, dmgen_c |
| Python | Колесо из «Загрузок» — документация Python |
Статическая линковка — C++ API
libdmgen.a входит в вашу программу целиком: рядом с ней ничего класть не нужно, кроме файла ключа dmgen.key (см. «Лицензия»). Нужен компилятор C++20 с той же стандартной библиотекой C++, что и у поставки (той же или более новой версии).
libdmgen.a собрана MinGW-w64 GCC — MSVC её не слинкует, нужен тот же тулчейн: MSYS2, консоль MINGW64 (не UCRT64), пакеты pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-pkgconf. Из MSVC — динамически, через dmgen_c. Строка линковки — из dmgen.pc; пути в нём считаются от места самого файла, так что каталог распаковки может быть любым:
$env:PKG_CONFIG_PATH = "C:\куда\распакован\lib\pkgconfig"
pkg-config --static --cflags --libs dmgenСистемные winhttp, crypt32, shell32 и advapi32 (проверка лицензии) уже прописаны в пакете.
В meson — зависимость по имени пакета:
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 для неё нет — пути указываются напрямую.
MinGW-w64 GCC — через библиотеку импорта lib\dmgen_c.dll.a:
gcc main.c -o мояпрограмма.exe -I C:/куда/распакован/include -L C:/куда/распакован/lib -ldmgen_cMSVC — файла .lib в поставке нет, его делают из самой DLL. В консоли MSYS2 — описание экспорта:
gendef dmgen_c.dll # пакет mingw-w64-x86_64-tools; пишет dmgen_c.defзатем в Developer Command Prompt for VS (x64) — библиотека импорта и сборка:
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.
Колесо Python — обёртка как раз над dmgen_c, библиотека лежит внутри пакета: документация Python.
Быстрый старт
Код «Честного знака» → файл PNG. Всё, что нужно, — один заголовок:
#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>>.
Кодирование
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 и «Честный знак»
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 для штрихкода не рекомендуется. |
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.
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), с комментариями самого заголовка (они по-английски):
#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 и рисование готовой матрицы лицензии не требуют. Лицензия привязана к оборудованию (материнская плата, процессор, системный диск), а не к установке ОС; пробный период и лицензия не зависят от библиотеки распознавания на той же машине.
#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_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 дней) выдаётся в личном кабинете. Ключ лицензии «на машины» в контейнере не активируется.Подробнее о лицензии на экземпляры.
Каждый процесс — отдельный экземпляр. Если программа запускает рабочие процессы через fork уже после загрузки библиотеки (gunicorn с --preload, multiprocessing, uWSGI без lazy-apps), каждый рабочий процесс занимает своё место при первом построении кода, а главный процесс, который сам кодов не строит, освобождает своё в течение 30 минут. Мест нужно столько, сколько процессов работает одновременно. Процесс, завершённый без штатного выхода (os._exit, kill -9), освобождает место через час.
Лицензия на экземпляры файлом не активируется: экземпляру нужна связь с сервером лицензий, без неё он работает 7 дней с последнего отчёта. Обычную машину без интернета (лицензия на машины) можно активировать файлом на весь оплаченный срок: при загрузке запроса в личном кабинете отметьте «Машина без интернета — работать весь срок без связи».
Командная строка
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.
Нужной функции нет в библиотеке или ваш случай за её границами — доработаем под вашу задачу. Напишите нам →