KasperskyOS Community Edition 1.3

Использование объектов KosObject (objects.h)

API определен в заголовочном файле sysroot-*-kos/include/kos/objects.h из состава KasperskyOS SDK.

API позволяет использовать типизированные объекты KosObject. Объект KosObject представляет собой регион памяти процесса, состоящий из сегментов со служебными и полезными данными. Служебные данные включают указатель на структуру, описывающую тип объекта, счетчик ссылок на объект и другие сведения об объекте. Состав полезных данных может быть любым в зависимости от назначения объекта. Например, сегменты полезных данных в объекте, который представляет собой абстракцию устройства, хранят структуры, которые содержат параметры функционирования устройства, указатели на низкоуровневые методы работы с ним, а также параметры программно-аппаратных интерфейсов для управления устройством.

Для объектов KosObject поддерживается механизм наследования типов. Например, абстракция устройства NS16550 UART содержит в разных сегментах полезных данных следующие структуры: специфичную для типа устройств NS16550 UART, специфичную для класса устройств UART, общие для любых устройств. Тип абстракции устройства NS16550 UART соответствует только той структуре, которая специфична для устройств NS16550 UART. Все остальные структуры соответствуют типам, которые унаследовал тип абстракции устройства NS16550 UART.

В API указателем на объект является указатель на сегмент полезных данных в этом объекте.

Сведения о функциях API приведены в таблице ниже.

Создание типа объектов

Созданию объектов предшествует создание их типа. Тип объектов представляет собой регион памяти процесса, содержащий структуру, которая включает такие данные, как имя типа, указатели на функции, вызываемые при создании и уничтожении объектов этого типа, указатель на родительский тип, счетчик ссылок на тип. В каждом объекте хранится указатель на такую структуру, что делает объекты типизированными.

Чтобы создать тип объектов, нужно вызвать функцию KosCreateObjectType() или KosCreateObjectTypeEx(). В отличие от функции KosCreateObjectType() функция KosCreateObjectTypeEx() позволяет создать тип, наследующий другие типы. Такой тип содержит адрес родительского типа, заданного через параметр parentType. При этом через параметр parentType можно задать тип, который также содержит адрес своего родительского типа. В итоге, используя функцию KosCreateObjectTypeEx(), можно создать дерево наследования типов. Каждый тип в этом дереве будет наследовать всю цепочку типов, образующих путь от корня дерева до этого типа.

В зависимости от того, используется наследование типов или нет, объекты могут быть простыми и составными. Объекты, которые соответствуют одному типу, являются простыми. Объекты, которые соответствуют цепочке наследования типов, являются составными. Составные объекты состоят из простых. Число простых объектов в составном равно числу типов в цепочке наследования. При этом эти простые объекты образуют цепочку наследования, соответствующую цепочке наследования их типов, то есть каждый объект, кроме первого в цепочке наследования, содержит адрес родительского объекта.

Через параметр defaultObjSize функций KosCreateObjectType() и KosCreateObjectTypeEx() нужно задать размер объектов по умолчанию (при создании объекта можно задать другой размер). В случае создания типа, наследующего другие типы, этот параметр имеет отношение только к последнему типу в цепочке наследования. Фактически параметр defaultObjSize задает минимальный размер сегмента полезных данных в простых объектах, поскольку действительный размер объектов будет больше заданного из-за выравнивания регионов памяти, наследования типов и наличия сегментов со служебными данными.

Через параметр ops функций KosCreateObjectType() и KosCreateObjectTypeEx() можно задать callback-функции, вызываемые при создании и уничтожении объектов (можно задать обе функции или только одну). При создании составного объекта внутри него создается набор простых объектов, а при уничтожении составного объекта внутри него уничтожается набор простых объектов. При создании и уничтожении каждого простого объекта вызываются отдельные callback-функции, заданные при создании типа этого объекта. Первым создается первый объект в цепочке наследования, последним создается последний объект цепочке наследования. Первым уничтожается последний объект в цепочке наследования, последним уничтожается первый объект в цепочке наследования.

Callback-функция, вызываемая при создании объекта, получает указатели на объект и данные, переданные функции KosCreateObjectEx() через параметр context. В этой callback-функции можно, например, выделить ресурсы, инициализировать данные в объекте. Если код возврата будет отличным от rcOk, объект не будет создан. Если при создании составного объекта не будет создан хотя бы один простой объект, то этот составной объект не будет создан. Также при создании составного объекта данные, переданные функции KosCreateObjectEx() через параметр context, получит только та callback-функция, которая вызывается при создании последнего простого объекта в цепочке наследования.

Callback-функция, вызываемая при уничтожении объекта, получает указатель на объект. В этой callback-функции можно, например, освободить ресурсы. Код возврата может быть произвольным.

Создание объекта

После создания типа объектов можно создавать объекты. Чтобы создать объект, нужно вызвать функцию KosCreateObject() или KosCreateObjectEx().

Через параметр type нужно задать тип объекта. Если задать тип, не наследующий другие типы, будет создан простой объект. Если задать тип, наследующий другие типы, будет создан составной объект, в котором последний простой объект в цепочке наследования будет иметь заданный тип.

Через параметр size нужно задать размер объекта или указать 0, чтобы был задан размер объекта по умолчанию, указанный в типе этого объекта. В случае создания составного объекта этот параметр имеет отношение только к последнему простому объекту в цепочке наследования. Фактически параметр size задает минимальный размер сегмента полезных данных в простом объекте, поскольку действительный размер объекта будет больше заданного из-за выравнивания региона памяти, наследования типов и наличия сегментов со служебными данными.

В отличие от функции KosCreateObject() у функции KosCreateObjectEx() есть параметр context, через который можно передать данные callback-функции, вызываемой при создании объекта. При создании составного объекта данные, переданные через параметр context, получит только та callback-функция, которая вызывается при создании последнего простого объекта в цепочке наследования.

Через параметр outObject функции KosCreateObject() и KosCreateObjectEx() передают указатель на созданный объект. Указатель на созданный составной объект представляет собой указатель на последний простой объект в цепочке наследования.

После создания объект можно использовать для записи данных в него и чтения данных из него.

Получение доступа к простым объектам в составном объекте

Чтобы получать доступ к простым объектам в составном объекте, нужно использовать функцию KosGetObjectParent() и/или функцию KosGetObjectAncestor(). Функция KosGetObjectParent() позволяет получить указатель на объект, который является непосредственным предком заданного объекта. Функция KosGetObjectAncestor() позволяет получить указатель на объект, который является предком заданного объекта и имеет заданный тип.

Управление временем жизни объектов и их типов

Объект существует, пока счетчик ссылок на него имеет значение больше нуля. Также тип объектов существует, пока счетчик ссылок на него имеет значение больше нуля. При создании объекта или типа объектов значение счетчика ссылок равно 1. В дальнейшем этот счетчик можно инкрементировать и декрементировать для управления временем жизни объекта или типа объектов. Например, после создания объекта можно декрементировать счетчик ссылок на его тип, поскольку при создании объекта библиотека libkos инкрементирует счетчик ссылок на тип этого объекта. В этом случае тип объекта будет уничтожен автоматически после уничтожения объекта, так как библиотека libkos декрементирует счетчик ссылок на тип объекта при уничтожении объекта. Также, к примеру, при сохранении адреса объекта в другом объекте нужно инкрементировать счетчик ссылок на первый объект, чтобы обеспечить его существование на время существования второго объекта. При уничтожении объекта, который содержит адрес другого объекта, нужно декрементировать счетчик ссылок на второй объект, чтобы обеспечить его уничтожение при отсутствии других ссылок.

Время жизни простого объекта в составном соответствует времени жизни этого составного объекта. Отдельно управлять временем жизни простого объекта в составном нельзя.

Чтобы инкрементировать счетчик ссылок на объект или тип объектов, нужно вызвать функцию KosRefObject() или KosRefObjectType() соответственно.

Чтобы декрементировать счетчик ссылок на объект или тип объектов, нужно вызвать функцию KosPutObject() или KosPutObjectType() соответственно.

Проверка типа объектов

Функции KosCheckParentType() и KosObjectTypeInheritsType() позволяют проверить, является ли один тип объектов родительским для другого.

Функция KosObjectOfType() проверяет, имеет ли объект заданный тип.

Функция KosObjectInheritsType() проверяет, имеет ли объект заданный тип или тип, наследующий заданный тип.

Получение типа и имени объекта

Чтобы получить тип объекта, нужно вызвать функцию KosObjectGetType().

Чтобы получить имя объекта, нужно вызвать функцию KosGetObjectName(). (Каждый простой объект в составном имеет имя этого составного объекта.)

Получение имени типа объектов

Чтобы получить имя типа объектов, нужно вызвать функцию KosObjectGetTypeName().

Сведения о функциях API

Функции objects.h