KasperskyOS Community Edition 1.3

Using KosStrings (strings.h)

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

The API lets you use KosStrings, which have the following distinguishing characteristics:

1. A KosString is a C-string (with a terminating zero) that follows the header containing the service data.
2. KosStrings are stored in hash tables, which are arrays whose elements are lists of strings. (The pointers for creating linked lists of strings are stored in the headers of strings.) Each list consists of one or more strings. Each list contains the strings who have the same value for the remainder after dividing the hash value of the string by the number of lists in the hash table. The main property of a hash table is that the computational complexity of searching for a string does not depend on the degree of occupancy of this table if all lists include only one string.

   When adding KosStrings to a hash table in real-world scenarios, lists containing multiple strings may be created. This leads to varying computational complexity when searching for strings in the hash table for the following reason. When searching for a key, the hash value is calculated and then converted into a string list index (by calculating the remainder from dividing the hash value by the number of lists). If there is only one string in the list containing the calculated index, the search will be complete after comparing this string to the key. However, if there are multiple strings in the list containing the calculated index, you may need to compare the key to all strings in this list to complete the search. In this case, the computational complexity of searching for a string may be higher than when there is only one string in the list.

3. KosStrings from one hash table are unique, which means that there are no identical strings in a hash table. If the strings from one hash table have different IDs, that means that these are different strings. (In the API, the ID of the KosString is the pointer to this string.) This lets you compare strings based on their IDs instead of their contents, thereby ensuring that the computational complexity of the comparison does not depend on the sizes of strings.
4. The size of a KosString is stored in the header instead of being calculated based on a search for a terminating zero, thereby ensuring that the computational complexity of getting the size does not depend on the actual size of the string.
5. KosStrings cannot be modified. This characteristic is a result of characteristics 2–4. Modification of a string may lead to the appearance of identical strings in the same hash table, a discrepancy between the actual size of a string and the size stored in the header, and a discrepancy between the string contents and the index of the string list in which this string is listed in the hash table.
6. A KosString exists as long as the counter for links to it remains greater than zero. (The string links counter is stored in the header.)

Information about API functions is provided in the table below.

Creating a hash table

You can use the default hash table, which is created automatically during initialization of the libkos library. This table may include no more than 2039 lists of strings with a string size of no more than 65,524 bytes without taking into account the terminating zero.

You can create a hash table with the required maximum number of string lists and the required maximum size of strings by calling the KosCreateStringRoot() function.

A hash table is created empty without any strings.

Adding a KosString to a hash table

To add a string to the default hash table, call the KosCreateString() function.

To add a string to a defined hash table, call the KosCreateStringEx() function.

If the string being added is already listed in the hash table, these functions do not add a new string but instead pass the ID of the already existing string via the outStr parameter.

Searching for a KosString in a hash table

To search for a string in the default hash table, call the KosGetString() function.

To search for a string in a defined hash table, call the KosGetStringEx() function.

The search is completed successfully if the key completely matches the string.

Managing the lifetime of KosStrings

A string exists as long as the counter for links to it remains greater than zero. The KosCreateString() and KosCreateStringEx() functions add a string whose links counter has a value of 1 to the hash table. If the string has already been added to the hash table, these functions increment the counter for links to this string. The KosGetString() and KosGetStringEx() functions increment the counter for links to the found string. This counter can then be incremented or decremented to manage the lifetime of the string. When passing the ID of a string to another program component, you must increment the counter for links to the corresponding string to ensure that this string will exist for the amount of time required by this component. If the string is no longer needed, you must decrement the counter for links to this string to ensure that it is destroyed when no other links remain.

To increment the counter for links to a string, call the KosRefString() or KosRefStringEx() function.

To decrement the counter for links to a string in the default hash table, call the KosPutString() function.

To decrement the counter for links to a string in a defined hash table, call the KosPutStringEx() function.

Getting the size of a KosString

To get the size of a string without taking into account the terminating zero, call the KosGetStringLen() function.

To get the size of a string while taking into account the terminating zero, call the KosGetStringSize() function.

Deleting a hash table

To delete a hash table, call the KosDestroyStringRoot() function. The table will be deleted only if it is empty.

Information about API functions

strings.h functions