The API is defined in the header file sysroot-*-kos/include/kos/basecontainer.h from the KasperskyOS SDK.
Information about API functions and macros is provided in the table below.
Creating a container
To create a container, call the KosBaseContainerCreateContainer() 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 KosBaseContainerInsertObject() function. You can add any KosObject, including a KosObjContainer, KosObjContainerNolock or KosBaseContainer. You cannot add the same object multiple times. When an object is added to a container, the reference counter for this object is incremented.
Adding objects to a container from another container
To add objects to a container from another container, call the KosBaseContainerAppend() function. The source container does not change.
Removing an object from a container
To remove an object from a container, call the KosBaseContainerRemoveObject() function. When an object is removed from a container, the reference counter for this object is decremented.
Moving an object to another container
To move an object from one container to another container, call the KosBaseContainerMoveObject() function.
Navigation within a container
To initialize an iterator for navigation within a container and to gain access to objects, call the KosBaseContainerIteratorInit() function. After initialization, the iterator is in the initial position.
To move the iterator to the next position, call the KosBaseContainerIteratorNext() function.
To check whether the iterator is in the final position, call the KosBaseContainerIteratorIsEnd() function.
To get the object corresponding to the current position of the iterator, call the KosBaseContainerIteratorGetObject() function.
Traversing objects in a container
To traverse objects in a container, use the KosBaseContainerWalkObjects() function or the KosBaseContainerIteratorForEachObject() macro.
When using the KosBaseContainerWalkObjects() 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 KosBaseContainerWalkObjects() function via the context parameter. If the callback function returns a value with the KOS_OBJECT_WALK_FINISH flag, the KosBaseContainerWalkObjects() function stops traversal. If a callback function returns a value with the KOS_OBJECT_WALK_REMOVE_OBJECT flag, the KosBaseContainerWalkObjects() 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.)
The KosBaseContainerIteratorForEachObject() macro is expanded into the header of the for operator. The pointer defined in the obj parameter will contain the address of the next object in each iteration. You can use this pointer to perform operations with objects. For example, you can delete an object from a container by calling the KosBaseContainerRemoveObject() function.
Objects in child containers are not traversed.
Enumerating objects in a container
To enumerate objects in a container, call the KosBaseContainerEnumContainerObjects() function. The order of object enumeration matches the order in which these objects are added to the container. Objects in child containers are not enumerated. This function increments the reference counter for the object. If this object is no longer needed, you need to decrement the reference counter by calling the KosPutObject() function from the objects.h API.
Getting the number of objects in a container
To get the number of objects in a container, call the KosBaseContainerCount() function. Objects in child containers are not taken into account.
Clearing a container
To remove all objects from a container, call the KosBaseContainerClear() function. This function decrements the counters for links to objects that are removed from the container.
Deleting a container
To delete a container, call the KosBaseContainerDestroyContainer() function. When a container is deleted, the counters for links to objects within this container are decremented.
Information about API functions and macros
basecontainer.h functions and macros
Function/Macro |
Information about the function/macro |
|---|---|
|
Purpose Creates a container. Parameters
Returned values If successful, the function returns |
|
Purpose Deletes a container. Parameters
Returned values If successful, the function returns |
|
Purpose Adds an object to a container. Parameters
Returned values If successful, the function returns |
|
Purpose Removes an object from a container. Parameters
Returned values If successful, the function returns |
|
Purpose Moves an object from one container into another. Parameters
Returned values If successful, the function returns |
|
Purpose Traverses objects in a container and calls the defined function for each object during traversal. Parameters
Returned values If successful, the function returns |
|
Purpose Enumerates objects in a container. Parameters
Returned values Pointer to the object. If the index value is exceeded, the function returns |
|
Purpose Gets the number of objects in a container. Parameters
Returned values Number of objects in a container. |
|
Purpose Clears a container. Parameters
Returned values If successful, the function returns |
|
Purpose Adds objects to a container from another container. Parameters
Returned values If successful, the function returns |
|
Purpose Initializes an iterator for navigation within a container and receives access to objects. Parameters
Returned values Initialized iterator for navigation within a container and access to objects. |
|
Purpose Checks whether the iterator is in the final position. Parameters
Returned values If the verification is successful, the function returns |
|
Purpose Gets the object corresponding to the current position of the iterator. Parameters
Returned values Pointer to the object. If the iterator is in the final position, the function returns |
|
Purpose Moves the iterator to the next position. Parameters
Returned values N/A |
|
Purpose Traverses objects in a container. Parameters
Macro values N/A |