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

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

API позволяет создавать таблицы числовых идентификаторов, связанных с объектами KosObject(об объектах KosObject см. "Использование объектов KosObject (objects.h)"). Использование такой таблицы позволяет проверить, является ли идентификатор действительным, перед его преобразованием в указатель на объект KosObject. Например, был создан объект KosObject, и указатель на этот объект был преобразован в числовой идентификатор, который затем был поврежден. Для выполнения операций с объектом KosObject этот идентификатор должен быть преобразован в указатель. Перед этим преобразованием выполнится поиск идентификатора в таблице, в результате чего с большой вероятностью будет обнаружено, что идентификатор недействительный, и будет получена ошибка. Если бы в этом примере для идентификации объекта KosObject использовался напрямую указатель, то повреждение этого указателя могло бы привести к неопределенным последствиям, возможно без получения ошибки.

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

Создание таблицы идентификаторов объектов

Чтобы создать таблицу идентификаторов объектов, нужно вызвать функцию KosCreateObjHandleTable(). Функция создает таблицу, содержащую то число идентификаторов, которое задано в параметре initialCount. Если при последующем использовании таблицы это число окажется недостаточным, будут автоматически добавлены дополнительные идентификаторы. Максимальное число идентификаторов (с учетом добавляемых после создания таблицы) задается в параметре maxCount.

Связывание объекта с идентификатором в таблице

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

Получение указателя на объект по идентификатору в таблице

Чтобы получить указатель на объект по идентификатору в таблице, нужно вызвать функцию KosRefObjectByObjHandle(). Функция инкрементирует счетчик ссылок на объект. Если полученный указатель на объект больше не требуется, нужно декрементировать счетчик ссылок на объект вызовом функции KosPutObject() из API objects.h.

Удаление связи объекта с идентификатором в таблице

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

Обход объектов, связанных с идентификаторами в таблице

Чтобы выполнить обход объектов, связанных с идентификаторами в таблице, нужно вызвать функцию KosWalkObjHandleTable(). Через параметр callback нужно задать callback-функцию, которая вызывается для каждого объекта при обходе и получает указатели на объект и данные, переданные функции KosWalkObjHandleTable() через параметр context. Callback-функция не должна вызывать другие функции API. Если callback-функция возвращает значение с флагом KOS_OBJECT_WALK_FINISH, то функция KosWalkObjHandleTable() прекращает обход. Если callback-функция возвращает значение с флагом KOS_OBJECT_WALK_REMOVE_OBJECT, то функция KosWalkObjHandleTable() декрементирует счетчик ссылок на соответствующий объект. (Флаги определены в заголовочном файле sysroot-*-kos/include/kos/objects.h из состава KasperskyOS SDK.)

Удаление таблицы идентификаторов объектов

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

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

Функции objhandles.h

Функция	Сведения о функции
`KosCreateObjHandleTable()`	Назначение Создает таблицу идентификаторов объектов. Параметры [in] `initialCount` – начальная емкость таблицы (число идентификаторов). [in] `maxCount` – максимальная емкость таблицы (число идентификаторов). [out] `createdTable` – указатель на адрес таблицы. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если в параметре `createdTable` указано значение `RTL_NULL`, или в параметре `maxCount` указан `0`, или значение в параметре `initialCount` превышает значение в параметре `maxCount`, или значение в параметре `maxCount` превышает максимально возможное, возвращает `rcInvalidArgument`. Если недостаточно памяти для выполнения требуемых операций, возвращает `rcOutOfMemory`.
`KosCreateObjHandle()`	Назначение Связывает объект с идентификатором в таблице. Параметры [in] `table` – указатель на таблицу идентификаторов объектов. [in] `object` – указатель на объект. [out] `createdHandle` – указатель на идентификатор объекта. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если в любом параметре указано значение `RTL_NULL`, возвращает `rcInvalidArgument`. Если недостаточно памяти для выполнения требуемых операций, возвращает `rcOutOfMemory`.
`KosRefObjectByObjHandle()`	Назначение Позволяет получить указатель на объект по идентификатору в таблице. Параметры [in] `table` – указатель на таблицу идентификаторов объектов. [in] `handle` – идентификатор объекта. [out] `refObject` – указатель на адрес объекта. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если в параметре `table` или `refObject` указано значение `RTL_NULL`, возвращает `rcInvalidArgument`. Если в параметре `handle` указан недействительный идентификатор объекта, возвращает `rcResourceNotFound`.
`KosCloseObjHandle()`	Назначение Удаляет связь объекта с идентификатором в таблице. Параметры [in] `table` – указатель на таблицу идентификаторов объектов. [in] `handle` – идентификатор объекта. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если в параметре `table` указано значение `RTL_NULL`, возвращает `rcInvalidArgument`. Если в параметре `handle` указан недействительный идентификатор объекта, возвращает `rcResourceNotFound`.
`KosWalkObjHandleTable()`	Назначение Выполняет обход объектов, связанных с идентификаторами в таблице, и вызывает заданную функцию для каждого объекта при обходе. Параметры [in] `table` – указатель на таблицу идентификаторов объектов. [in] `callback` – идентификатор callback-функции, вызываемой для каждого объекта при обходе. Тип параметра определен в заголовочном файле `sysroot-*-kos/include/kos/objects.h` из состава KasperskyOS SDK. [in,optional] `context` – указатель на данные, которые будут переданы callback-функции, заданной через параметр `callback`. Можно указать `RTL_NULL`, если данные передавать не требуется. Callback-функция получит переданные данные через свой параметр `context`. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если в параметре `table` или `callback` указано значение `RTL_NULL`, возвращает `rcInvalidArgument`.
`KosDestroyObjHandleTable()`	Назначение Удаляет таблицу идентификаторов объектов, а также опционально выполняет обход объектов, связанных с идентификаторами в таблице, и вызывает заданную функцию для каждого объекта при обходе. Параметры [in] `table` – указатель на таблицу идентификаторов объектов. [in,optional] `callback` – идентификатор callback-функции, вызываемой для каждого объекта при обходе, или `RTL_NULL`, если не требуется использовать callback-функцию. Тип параметра определен в заголовочном файле `sysroot-*-kos/include/kos/objects.h` из состава KasperskyOS SDK. [in,optional] `context` – указатель на данные, которые будут переданы callback-функции, заданной через параметр `callback`. Можно указать `RTL_NULL`, если в параметре `callback` указано значение `RTL_NULL`, или не требуется передавать данные функции, заданной через параметр `callback`. Callback-функция получит переданные данные через свой параметр `context`. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если в параметре `table` указано значение `RTL_NULL`, возвращает `rcInvalidArgument`. Если в параметре `callback` указано значение `RTL_NULL`, а в параметре `context` указано значение, отличное от `RTL_NULL`, возвращает `rcInvalidArgument`.

В начало