Using KosObjContainers (objcontainer.h)

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

Information about API functions is provided in the table below.

Creating a container

To create a container, call the KosCreateObjContainer() function. In the parent parameter, you can specify the ID of the parent container, which is the KosObjContainer, KosObjContainerNolock or KosBaseContainer to which the created container will be added.

Adding an object to a container

To add an object to a container, call the KosInsertObjContainerObject() function. You can add any KosObject, including a KosObjContainer, KosObjContainerNolock or KosBaseContainer. You must use the name parameter to define the object name that this object will have within the container. This name is not related to the name that was defined when the object was created. The name of an object within a container must be unique. You can add the same object multiple times with different names. When an object is added to a container, the reference counter for this object is incremented.

Removing an object from a container

To remove an object from a container, call the KosRemoveObjContainerObjectByName() or KosRemoveObjContainerObject() function. When an object is removed from a container, the reference counter for this object is decremented.

Searching for an object in a container

To search for an object with the defined name in a container, call the KosGetObjContainerObjectByName() function. Child containers will not be searched for the object. This function increments the reference counter for the found object.

Traversing objects in a container

To traverse objects in a container, call the KosWalkObjContainerObjects() function. Use the walk 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 KosWalkObjContainerObjects() 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 KosWalkObjContainerObjects() function stops traversal. If a callback function returns a value with the KOS_OBJECT_WALK_REMOVE_OBJECT flag, the KosWalkObjContainerObjects() function removes the corresponding object from the container. (The flags are defined in the header file sysroot-*-kos/include/kos/objects.h from the KasperskyOS SDK.)

Objects in child containers are not traversed.

Enumerating the names of objects in a container

To enumerate the names of objects in a container, use the KosEnumObjContainerNames() function. The order of enumeration for object names matches the order in which these objects are added to the container. Object names in child containers are not enumerated. The function increments the reference counter for the KosString containing the object name. If this string is no longer needed, you need to decrement the reference counter for it by calling the KosPutString() function from the strings.h API.

Getting the number of objects in a container

To get the number of objects in a container, call the KosCountObjContainerObjects() function. Objects in child containers are not taken into account.

Clearing a container

To remove all objects from a container, call the KosClearObjContainer() function. This function decrements the counters for links to objects that are removed from the container.

Checking whether an object is a container

To check whether an object is a KosObjContainer, call the KosIsContainer() function.

Deleting a container

To delete a container, call the KosDestroyObjContainer() function. When a container is deleted, the counters for links to objects within this container are decremented.

Information about API functions

objcontainer.h functions

Function	Information about the function
`KosCreateObjContainer()`	Purpose Creates a container. Parameters [in,optional] `parent` – ID of the parent container, or `RTL_NULL` if you do not need to add the created container to an already existing container. [in] `name` – pointer to the name of the created container. The maximum size (bytes) of a container name matches the value of the `KOS_OBJ_CONTAINER_NAME_MAX` constant. [out] `outContainer` – pointer to the ID of the created container. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosDestroyObjContainer()`	Purpose Deletes a container. Parameters [in] `container` – ID of the container. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosInsertObjContainerObject()`	Purpose Adds an object to a container. Parameters [in] `container` – ID of the container. [in] `name` – pointer to the object name. [in] `object` – pointer to the object. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosRemoveObjContainerObjectByName()`	Purpose Removes the object with the defined name from a container. Parameters [in] `container` – ID of the container. [in] `name` – pointer to the object name. [in,optional] `object` – pointer to the object, or `RTL_NULL` if you do not need to verify that the object name defined via the `name` parameter matches the object being removed. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosRemoveObjContainerObject()`	Purpose Removes an object from a container. Parameters [in] `container` – ID of the container. [in] `object` – pointer to the object. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosGetObjContainerObjectByName()`	Purpose Searches a container for the object with the defined name. Parameters [in] `container` – ID of the container. [in] `name` – pointer to the name of the object that you are searching for. [out] `outObject` – pointer to the address of the found object. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. Additional information If an object with the defined name is not found, the function returns the `RTL_NULL` value via the `outObject` parameter.
`KosWalkObjContainerObjects()`	Purpose Traverses objects in a container and calls the defined function for each object during traversal. Parameters [in] `container` – ID of the container. [in] `walk` – 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 `walk` 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.
`KosEnumObjContainerNames()`	Purpose Enumerates the names of objects in a container. Parameters [in] `container` – ID of the container. [in] `index` – index for enumerating object names. Enumeration starts with zero. [out] `outStr` – pointer to the ID of the `KosString` containing the object name. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosCountObjContainerObjects()`	Purpose Gets the number of objects in a container. Parameters [in] `container` – ID of the container. Returned values Number of objects in a container.
`KosClearObjContainer()`	Purpose Clears a container. Parameters [in] `container` – ID of the container. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosIsContainer()`	Purpose Checks whether an object is a `KosObjContainer`. Parameters [in] `object` – pointer to the object. Returned values If the verification is successful, the function returns `rtl_true`, otherwise it returns `rtl_false`.

Page top