KasperskyOS Community Edition 1.3

Using KosObjects (objects.h)

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

The API lets you use typified KosObjects. A KosObject is a process memory region consisting of segments containing service data and payload data. Service data includes a pointer to the structure describing the object type, a counter for links to the object, and other information about the object. Payload data may consist of any data depending on the purpose of the object. For example, segments of payload data in an object representing a device abstraction save the structures that contain the device operating parameters, pointers to low-level methods for working with the device, and the parameters of software/hardware interfaces for device management.

A type inheritance mechanism is supported for KosObjects. For example, an abstraction of the NS16550 UART device contains the following structures in different segments of payload data: a structure specific to NS16550 UART devices, a structure specific to the UART device class, and common structures for all devices. The NS16550 UART device abstraction type corresponds only to the structure that is specific to NS16550 UART devices. All other structures correspond to types that inherited the NS16550 UART device abstraction type.

In the API, the pointer to an object is the pointer to the segment of payload data in this object.

Information about API functions is provided in the table below.

Creating an object type

An object type is created before objects are created. An object type is a process memory region containing the structure that includes data such as the type name, pointers to functions that are called when objects of this type are created and destroyed, a pointer to the parent type, and a counter for links to the type. Each object stores the pointer to this structure, which means that the objects are typified.

To create an object type, call the KosCreateObjectType() or KosCreateObjectTypeEx() function. In contrast to the KosCreateObjectType() function, the KosCreateObjectTypeEx() function lets you create a type that inherits other types. This type contains the address of the parent type that is defined via the parentType parameter. You can also use the parentType parameter to define a type that also contains the address of its parent type. As a result, you can use the KosCreateObjectTypeEx() function to create a type inheritance tree. Each type in this tree will inherit the entire chain of types that form the path from the root of the tree to this specific type.

Depending on whether type inheritance is being employed, objects may be simple or composite. Objects that correspond to one type are known as simple objects. Objects that correspond to a type inheritance chain are known as composite objects. Composite ones consist of simple objects. The number of simple objects in a composite object is equal to the number of types in the inheritance chain. The simple objects form an inheritance chain corresponding to the chain of inheritance of their types. In other words, each object except the first one in the inheritance chain contains the address of the parent object.

You need to use the defaultObjSize parameter of the KosCreateObjectType() and KosCreateObjectTypeEx() functions to define the default size of objects (you can define a different size when creating an object). When creating a type that inherits other types, this parameter pertains only to the last type in the inheritance chain. The defaultObjSize parameter effectively defines the minimum size of a segment of payload data in simple objects because the actual size of objects will be larger than the defined size due to the alignment of memory regions, inheritance of types, and the presence of segments containing service data.

You can use the ops parameter of the KosCreateObjectType() and KosCreateObjectTypeEx() functions to define the callback functions that are called when objects are created and destroyed (you can define both functions or just one of them). When a composite object is created, a set of simple objects is created within it. When the composite object is destroyed, the set of simple objects within it is also destroyed. When each simple object is created and destroyed, separate callback functions that were defined when creating the type of this object are called. The first object in the inheritance chain is created first, and the last object in the inheritance chain is created last. The last object in the inheritance chain is destroyed first, and the first object in the inheritance chain is destroyed last.

The callback function that is called when creating an object receives pointers to the object and the data passed to the KosCreateObjectEx() function via the context parameter. In this callback function, you can allocate resources and initialize data in an object, for example. If the return code differs from rcOk, the object will not be created. If a composite object is being created without creating at least one simple object, this composite object will not be created. Also, when creating a composite object, the data passed to the KosCreateObjectEx() function via the context parameter will be received only by the callback function that is called when creating the last simple object in the inheritance chain.

The callback function that is called when an object is destroyed receives the pointer to the object. In this callback function, you can free up resources, for example. Any return code is acceptable.

Creating an object

After creating an object type, you can create objects. To create an object, you must call the KosCreateObject() or KosCreateObjectEx() function.

Use the type parameter to define the object type. If you define a type that does not inherit other types, a simple object will be created. If you define a type that inherits other types, a composite object will be created and the last simple object in the inheritance chain for this composite object will have the defined type.

Use the size parameter to define the object size, or specify 0 to set the default object size specified in the type of this object. If a composite object is created, this parameter pertains only to the last simple object in the inheritance chain. The size parameter effectively defines the minimum size of a segment of payload data in a simple object because the actual size of the object will be larger than the defined size due to the alignment of the memory region, inheritance of types, and the presence of segments containing service data.

In contrast to the KosCreateObject() function, the KosCreateObjectEx() function has the context parameter, which can be used to pass data to the callback function that is called when an object is created. When creating a composite object, the data passed via the context parameter will be received only by the callback function that is called when creating the last simple object in the inheritance chain.

The outObject parameter is used by the KosCreateObject() and KosCreateObjectEx() functions to transfer the pointer of the created object. The pointer to the created composite object is the pointer to the last simple object in the inheritance chain.

After it is created, the object can be used to write data to it and read data from it.

Obtaining access to simple objects in a composite object

To gain access to simple objects in a composite object, you need to use the KosGetObjectParent() function and/or the KosGetObjectAncestor() function. The KosGetObjectParent() function gets the pointer to the object that is the direct ancestor of the defined object. The KosGetObjectAncestor() function gets the pointer to the object that is the ancestor of the defined object and has the defined type.

Managing the lifetime of objects and their types

An object exists as long as the counter for links to that object has a value greater than zero. Likewise, an object type exists as long as the counter for links to that object has a value greater than zero. When an object or object type is created, the value of the links counter is equal to 1. This counter can then be incremented or decremented to manage the lifetime of the object or object type. For example, after an object is created, you can decrement the counter for links to its type because the libkos library increments the counter for links to this object type when an object is created. In this case, the object type will be destroyed automatically after the object is destroyed because the libkos library decrements the counter for links to the object type when an object is destroyed. In addition, when saving an object address in another object, you must increment the counter for links to the first object to ensure that it exists throughout the lifetime of the second object. When you destroy an object that contains the address of another object, you must decrement the counter for links to the second object to ensure that it is destroyed when no other links remain.

The lifetime of a simple object within a composite object corresponds to the lifetime of this composite object. You cannot separately manage the lifetime of a simple object within a composite object.

To increment the counter for links to an object or object type, call the KosRefObject() or KosRefObjectType() function, respectively.

To decrement the counter for links to an object or object type, call the KosPutObject() or KosPutObjectType() function, respectively.

Verifying an object type

The KosCheckParentType() and KosObjectTypeInheritsType() functions let you check whether one object type is a parent to another object type.

The KosObjectOfType() function verifies whether an object has the defined type.

The KosObjectInheritsType() function checks whether an object has the defined type or a type inherited by the defined type.

Getting the type and name of an object

To get the object type, call the KosObjectGetType() function.

To get the object name, call the KosGetObjectName() function. (Each simple object in a composite object has the name of this composite object.)

Getting the name of an object type

To get the name of an object type, call the KosObjectGetTypeName() function.

Information about API functions

objects.h functions