Using KosObjContainerNolock (objcontainernolock.h)

The API is defined in the header file sysroot-*-kos/include/kos/objcontainernolock.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 KosCreateObjContainerNolock() 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 KosInsertObjContainerNolockObject() 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 KosRemoveObjContainerNolockObjectByName() or KosRemoveObjContainerNolockObject() 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 KosGetObjContainerNolockObjectByName() function. Child containers will not be searched for the object. This function increments the reference counter for the found object.

Navigation within a container

To initialize an iterator for navigation within a container and to receive access to objects, call the KosInitObjContainerNolockIterator() function. After initialization, the iterator is in the initial position.

To move the iterator to the next position, call the KosNextObjContainerNolockIterator() function.

To check whether the iterator is in the final position, call the KosIsObjContainerNolockIteratorEnd() function.

To get the object corresponding to the current position of the iterator, call the KosGetObjContainerNolockIteratorObject() function.

Traversing objects in a container

To traverse objects in a container, use the KosWalkObjContainerNolockObjects() function or the KosForEachObjContainerNolockObject() macro.

When using the KosWalkObjContainerNolockObjects() 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 KosWalkObjContainerNolockObjects() function via the context parameter. If the callback function returns a value with the KOS_OBJECT_WALK_FINISH flag, the KosWalkObjContainerNolockObjects() function stops traversal. If a callback function returns a value with the KOS_OBJECT_WALK_REMOVE_OBJECT flag, the KosWalkObjContainerNolockObjects() 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 KosForEachObjContainerNolockObject() 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 KosRemoveObjContainerNolockObject() function.

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 KosEnumObjContainerNolockNames() 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 KosCountObjContainerNolockObjects() function. Objects in child containers are not taken into account.

Clearing a container

To remove all objects from a container, call the KosClearObjContainerNolock() 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 or KosObjContainerNolock, call the KosIsObjContainerNolock() function.

Deleting a container

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

Information about API functions and macros

objcontainernolock.h functions and macros

Function/Macro	Information about the function/macro
`KosCreateObjContainerNolock()`	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_UNSAFE_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.
`KosDestroyObjContainerNolock()`	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.
`KosClearObjContainerNolock()`	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.
`KosInsertObjContainerNolockObject()`	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.
`KosRemoveObjContainerNolockObjectByName()`	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.
`KosRemoveObjContainerNolockObject()`	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.
`KosGetObjContainerNolockObjectByName()`	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.
`KosWalkObjContainerNolockObjects()`	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.
`KosEnumObjContainerNolockNames()`	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.
`KosCountObjContainerNolockObjects()`	Purpose Gets the number of objects in a container. Parameters [in] `container` – ID of the container. Returned values Number of objects in a container.
`KosInitObjContainerNolockIterator()`	Purpose Initializes an iterator for navigation within a container and receives access to objects. Parameters [in] `container` – ID of the container. Returned values Initialized iterator for navigation within a container and access to objects.
`KosIsObjContainerNolockIteratorEnd()`	Purpose Checks whether the iterator is in the final position. Parameters [in] `iterator` – pointer to the iterator. Returned values If the verification is successful, the function returns `rtl_true`, otherwise it returns `rtl_false`.
`KosGetObjContainerNolockIteratorObject()`	Purpose Gets the object corresponding to the current position of the iterator. Parameters [in] `iterator` – pointer to the iterator. Returned values Pointer to the object. If the iterator is in the final position, the function returns `RTL_NULL`.
`KosNextObjContainerNolockIterator()`	Purpose Moves the iterator to the next position. Parameters [in] `iterator` – pointer to the iterator. Returned values N/A
`KosForEachObjContainerNolockObject()`	Purpose Traverses objects in a container. Parameters [in] `container` – ID of the container. [in] `obj` – pointer for saving the addresses of traversed objects. Macro values N/A
`KosIsObjContainerNolock()`	Purpose Checks whether the object is a `KosObjContainer` or `KosObjContainerNolock`. 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