Using KosObject identifiers (objhandles.h)

The API is defined in the header file sysroot-*-kos/include/kos/objhandles.h from the KasperskyOS SDK.

The API lets you create tables of numerical identifiers related to KosObjects (for details about KosObject, see Using KosObjects (objects.h)). By using this table, you can verify the validity of an ID before converting it into a pointer to a KosObject. For example, a KosObject was created and the pointer to this object was converted into a numerical identifier that was later corrupted. To perform operations with the KosObject, this identifier must be converted into a pointer. Before this conversion, a search is performed for the identifier in the table, and therefore it is highly likely that the invalidity of the identifier will be detected and an error will be received. If a direct pointer were used in this example to identify the KosObject, a corruption of this pointer could lead to unforeseen consequences, potentially without receiving an error.

Information about API functions is provided in the table below.

Creating an object identifier table

To create an object identifier table, call the KosCreateObjHandleTable() function. Creates a table containing the number of identifiers defined in the initialCount parameter. If this number turns out to be insufficient during subsequent use of the table, additional identifiers will be automatically added. The maximum number of identifiers (including those added after creating the table) is defined in the maxCount parameter.

Binding an object to an identifier in the table

To bind an object to an identifier in the table, call the KosCreateObjHandle() function. This function increments the reference counter for the object.

Getting a pointer to an object based on an identifier in the table

To get a pointer to an object based on an identifier in the table, call the KosRefObjectByObjHandle() function. This function increments the reference counter for the object. If the received pointer to the object is no longer required, you need to decrement the reference counter for the object by calling the KosPutObject() function from the objects.h API.

Unbinding an object from an identifier in the table

To unbind an object from an identifier in the table, call the KosCloseObjHandle() function. Decrements the reference counter for an object to balance the incrementation performed when calling the KosCreateObjHandle() function.

Traversing objects bound to identifiers in the table

To traverse objects bound to identifiers in the table, call the KosWalkObjHandleTable() function. Use the callback parameter to define the callback function that is called for each object during traversal and receives pointers to the object and data that is passed to the KosWalkObjHandleTable() function via the context parameter. The callback function must not call other API functions. If the callback function returns a value with the KOS_OBJECT_WALK_FINISH flag, the KosWalkObjHandleTable() function stops traversal. If a callback function returns a value with the KOS_OBJECT_WALK_REMOVE_OBJECT flag, the KosWalkObjHandleTable() function decrements the reference counter for the corresponding object. (The flags are defined in the header file sysroot-*-kos/include/kos/objects.h from the KasperskyOS SDK.)

Deleting the object identifier table

To delete the object identifier table, call the KosDestroyObjHandleTable() function. Prior to deleting the table, the function performs operations with the objects bound to identifiers in the table. If the callback parameter is set to RTL_NULL, the KosDestroyObjHandleTable() function decrements the reference counter for each object. If a callback function is defined via the callback parameter, the KosDestroyObjHandleTable() function calls this callback function for each object during traversal identically to the KosWalkObjHandleTable() function.

Information about API functions

objhandles.h functions

Function	Information about the function
`KosCreateObjHandleTable()`	Purpose Creates an object identifier table. Parameters [in] `initialCount` – initial capacity of the table (number of identifiers). [in] `maxCount` – maximum capacity of the table (number of identifiers). [out] `createdTable` – pointer to the table address. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the `createdTable` parameter is set to `RTL_NULL`, or the `maxCount` parameter is set to `0`, or the value in the `initialCount` parameter exceeds the value in the `maxCount` parameter, or the value in the `maxCount` parameter exceeds the maximum value, the function returns `rcInvalidArgument`. If there is insufficient memory to perform the required operations, the function returns `rcOutOfMemory`.
`KosCreateObjHandle()`	Purpose Binds an object to an identifier in the table. Parameters [in] `table` – pointer to the object identifier table. [in] `object` – pointer to the object. [out] `createdHandle` – pointer to the object ID. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If any parameter is set to `RTL_NULL`, the function returns `rcInvalidArgument`. If there is insufficient memory to perform the required operations, the function returns `rcOutOfMemory`.
`KosRefObjectByObjHandle()`	Purpose Gets a pointer to an object based on an identifier in the table. Parameters [in] `table` – pointer to the object identifier table. [in] `handle` – object identifier. [out] `refObject` – pointer to the object address. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the `table` or `refObject` parameter is set to `RTL_NULL`, the function returns `rcInvalidArgument`. If the `handle` parameter contains an invalid object identifier, the function returns `rcResourceNotFound`.
`KosCloseObjHandle()`	Purpose Unbinds an object from an identifier in the table. Parameters [in] `table` – pointer to the object identifier table. [in] `handle` – object identifier. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the `table` parameter is set to `RTL_NULL`, the function returns `rcInvalidArgument`. If the `handle` parameter contains an invalid object identifier, the function returns `rcResourceNotFound`.
`KosWalkObjHandleTable()`	Purpose Traverses objects bound to identifiers in the table, and calls the defined function for each object during traversal. Parameters [in] `table` – pointer to the object identifier table. [in] `callback` – ID of the callback function that is called for each object during traversal. The parameter type is defined in the header file `sysroot-*-kos/include/kos/objects.h` from the KasperskyOS SDK. [in,optional] `context` – pointer to the data that will be passed to the callback function that was defined via the `callback` parameter. You can specify `RTL_NULL` if data does not need to be passed. The callback function will receive the passed data through its own `context` parameter. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the `table` or `callback` parameter is set to `RTL_NULL`, the function returns `rcInvalidArgument`.
`KosDestroyObjHandleTable()`	Purpose Deletes the object identifier table, and also (optionally) traverses objects bound to identifiers in the table and calls the defined function for each object during traversal. Parameters [in] `table` – pointer to the object identifier table. [in,optional] `callback` – ID of the callback function that is called for each object during traversal, or `RTL_NULL` if a callback function is not needed. The parameter type is defined in the header file `sysroot-*-kos/include/kos/objects.h` from the KasperskyOS SDK. [in,optional] `context` – pointer to the data that will be passed to the callback function that was defined via the `callback` parameter. You can specify `RTL_NULL` if the `callback` parameter is set to `RTL_NULL` or if you do not need to pass data to a function defined via the `callback` parameter. The callback function will receive the passed data through its own `context` parameter. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the `table` parameter is set to `RTL_NULL`, the function returns `rcInvalidArgument`. If the `callback` parameter is set to `RTL_NULL` but the `context` parameter is set to a value other than `RTL_NULL`, the function returns `rcInvalidArgument`.

Page top