Creating handles

The handles of user resources are created by the providers of the resources. The KnHandleCreateUserObject() function declared in the coresrv/handle/handle_api.h header file is used to create handles of user resources.

handle_api.h (fragment)

/**

* Creates the specified handle of the specified type with the rights permissions mask.

* The "type" parameter can take values ranging from HANDLE_TYPE_USER_FIRST to

* HANDLE_TYPE_USER_LAST. The HANDLE_TYPE_USER_FIRST and HANDLE_TYPE_USER_LAST macros

* are defined in the handletype.h header file. The "context" parameter defines the context

* of the user resource.

* If successful, the function returns rcOk, otherwise it returns an error code.

*/

Retcode KnHandleCreateUserObject(rtl_uint32_t type, rtl_uint32_t rights,

void *context, Handle *handle);

The user resource context is the data that allows the resource provider to identify the resource and its state when access to the resource is requested by other programs. This normally consists of a data set with various types of data (structure). For example, the context of a file may include the name, path, and cursor position. The user resource context is used as the resource transfer context or is used together with multiple resource transfer contexts.

The type parameter of the KnHandleCreateUserObject() function is reserved for potential future use and does not affect the behavior of the function, but it must take a value from the interval specified in the function comments.

For details about a handle permissions mask, see "Handle permissions mask".