Dereferencing handles

When dereferencing a handle, the client program sends the server program the handle, and the server program receives a pointer to the resource transfer context, the permissions mask of the sent handle, and the ancestor of the handle sent by the client program and already owned by the server program. Dereferencing occurs when a client program that called methods for working with a resource (such as read/write or access closure) sends the server program the handle that was received from this server program when access to the resource was opened.

Dereferencing handles requires fulfillment of the same conditions and utilizes the same mechanisms and data types as when transferring handles. A handle dereferencing scenario includes the following steps:

1. The client program packages the handle into a field of the *_req request structure of the nk_handle_desc_t type.
2. The client program calls the interface method for sending the handle to the server program for the purpose of performing operations with the resource. This method executes the Call() system call.
3. The server program receives the request by executing the Recv() system call.
4. The dispatcher on the server program side calls the method corresponding to the request. This method verifies that the dereferencing operation was specifically executed instead of a handle transfer. Then the called method has the option to verify that the access rights of the dereferenced handle (that was sent by the client program) permit the requested actions with the resource, and extracts the pointer to the resource transfer context from the field of the *_req request structure of the nk_handle_desc_t type.

To perform verifications, the server program utilizes the nk_is_handle_dereferenced() and nk_get_badge_op() functions that are declared in the nk/types.h header file.

types.h (fragment)

/**

* Returns a value different from null if

* the handle in the transport container of

* "desc" is received as a result of dereferencing

* the handle. Returns null if the handle

* in the transport container of "desc" is received

* as a result of a handle transfer.

*/

static inline

nk_bool_t nk_is_handle_dereferenced(const nk_handle_desc_t *desc)

/**

* Extracts the pointer to the resource transfer context

* "badge" from the transport container of "desc"

* if the permissions mask that was put in the transport

* container of the desc handle has the operation flags set.

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

*/

static inline

nk_err_t nk_get_badge_op(const nk_handle_desc_t *desc,

nk_rights_t operation,

nk_badge_t *badge)

Generally, the server program does not require the handle that was received from dereferencing because the server program normally retains the handles that it owns, for example, within the contexts of user resources. However, the server program can extract this handle from the handle transport container if necessary.