Коды возврата

Общие сведения

В решении на базе KasperskyOS коды возврата функций различных API (например, API библиотеки libkos, ConfigManager, транспортного кода, прикладного ПО) имеют тип 32-битного знакового целого числа. Этот тип определен в заголовочном файле sysroot-*-kos/include/rtl/retcode.h из состава Kaspersky IoT Secure Gateway 1000 SDK так:

typedef __INT32_TYPE__ Retcode;

Множество кодов возврата состоит из кода успеха со значением 0 и кодов ошибок. Код ошибки интерпретируется как структура данных, формат которой описан в заголовочном файле sysroot-*-kos/include/rtl/retcode.h из состава Kaspersky IoT Secure Gateway 1000 SDK. Этот формат предусматривает наличие нескольких полей, которые содержат не только сведения о результатах вызова функции, но и следующую дополнительную информацию:

• Флаг в поле Customer, сигнализирующий о том, что код ошибки определен разработчиками решения на базе KasperskyOS, а не разработчиками ПО из состава Kaspersky IoT Secure Gateway 1000 SDK.

  Благодаря флагу в поле Customer разработчики решения на базе KasperskyOS и разработчики ПО из состава Kaspersky IoT Secure Gateway 1000 SDK могут определять коды ошибок из непересекающихся множеств.

• Глобальный идентификатор кода ошибки в поле Space.

  Глобальные идентификаторы позволяют определять непересекающиеся множества кодов ошибок.

  Например, идентификатору RC_SPACE_GENERAL соответствуют коды общих ошибок, идентификатору RC_SPACE_KERNEL соответствуют коды ошибок ядра, идентификатору RC_SPACE_DRIVERS соответствуют коды ошибок драйверов.

• Локальный идентификатор кода ошибки в поле Facility.

  Локальные идентификаторы позволяют определять непересекающиеся подмножества кодов ошибок в рамках множества кодов ошибок, которые соответствуют одному глобальному идентификатору. Например, множество кодов ошибок с глобальным идентификатором RC_SPACE_DRIVERS включает непересекающиеся подмножества кодов ошибок с локальными идентификаторами RC_FACILITY_I2C, RC_FACILITY_USB, RC_FACILITY_BLKDEV.

Глобальные и локальные идентификаторы специфичных кодов ошибок назначаются разработчиками решения на базе KasperskyOS и разработчиками ПО из состава Kaspersky IoT Secure Gateway 1000 SDK независимо друг от друга. То есть формируется два множества глобальных идентификаторов. Каждый глобальный идентификатор имеет уникальное смысловое значение в рамках одного множества. Каждый локальный идентификатор имеет уникальное смысловое значение в рамках множества локальных идентификаторов, относящихся к одному глобальному идентификатору. Общие коды ошибок могут использоваться в любых API.

Такой централизованный подход позволяет избежать появления в решении на базе KasperskyOS одинаковых кодов ошибок с разными смысловыми значениями. Это нужно, чтобы исключить проблему транзита кодов ошибок через разные API. То есть коды ошибок в решении на базе KasperskyOS назначаются так, чтобы не выполнять конвертацию этих кодов при транзите через разные API.

Приведенные здесь сведения о кодах возврата не относятся к функциям интерфейса POSIX и API стороннего ПО, используемого в решениях на базе KasperskyOS.

Общие коды возврата

Коды возврата, которые являются общими для API любых компонентов решения и их составных частей, определены в заголовочном файле sysroot-*-kos/include/rtl/retcode.h из состава Kaspersky IoT Secure Gateway 1000 SDK. Описание общих кодов возврата приведено в таблице ниже.

Общие коды возврата

Определение кодов ошибок

Чтобы определить код ошибки, разработчику решения на базе KasperskyOS нужно использовать макрос MAKE_RETCODE(), определенный в заголовочном файле sysroot-*-kos/include/rtl/retcode.h из состава Kaspersky IoT Secure Gateway 1000 SDK. При этом через параметр customer нужно передать символьную константу RC_CUSTOMER_TRUE.

Пример:

#define LV_EBADREQUEST MAKE_RETCODE(RC_CUSTOMER_TRUE, RC_SPACE_APPS, RC_FACILITY_LogViewer, 5, "Bad request")

Описание ошибки, которое передается через параметр desc, не используется макросом MAKE_RETCODE().

Чтение полей структуры кода ошибки

Макросы RC_GET_CUSTOMER(), RC_GET_SPACE(), RC_GET_FACILITY() и RC_GET_CODE(), определенные в заголовочном файле sysroot-*-kos/include/rtl/retcode.h из состава Kaspersky IoT Secure Gateway 1000 SDK, позволяют читать поля структуры кода ошибки.

Макросы RETCODE_HR_PARAMS() и RETCODE_HR_FMT(), определенные в заголовочном файле sysroot-*-kos/include/rtl/retcode_hr.h из состава Kaspersky IoT Secure Gateway 1000 SDK, используются для форматированного вывода сведений об ошибке.