zx_object_set_cookie

英文原文快照

名称

object_set_cookie —— 设置对象的cookie值。

概要

  1. #include <zircon/syscalls.h>
  3. zx_status_t zx_object_set_cookie(zx_handle_t handle, zx_handle_t scope, uint64_t cookie);

描述

某些类型的对象（事件，事件对，资源和VMO）可能会附加一个cookie，这是一个64位的不透明值。 在对象新创建时，cookie是未定义且不可读的。

成功调用zx_object_set_cookie() 后，cookie的值被修改，并且scope句柄引用的对象将成为读取或修改cookie所必需的键值。 scope在对象的生命周期内不可被更改。

事件对在cookie方面有些特别。 如果事件对的一端关闭，则另一端的cookie也将失效。 失效的cookie无法使用任何范围(scope)来获取或设置值。

Cookie对于将传递给另一个进程并在稍后返回的对象非常有用。 通过使用其他进程无法访问的scope作为参数调用zx_object_set_cookie() 设置cookie值，稍后可以使用zx_object_get_cookie() 来验证句柄是否由调用进程“创建”并同时返回该对象的本地状态的ID或指针。

当scope引用的对象被销毁或者该对象的句柄不可用时，cookie值不可再被修改或获取。

权限

TODO(ZX-2399)

返回值

zx_object_set_cookie() 执行成功则返回ZX_OK。 如果发生错误，将返回以下错误码之一。

错误码

ZX_ERR_BAD_HANDLE：handle或scope是无效句柄。

ZX_ERR_NOT_SUPPORTED：handle不是可以具有cookie集合（即事件，事件对，资源或VMO）的对象句柄。

ZX_ERR_ACCESS_DENIED：先前已使用另一个对象作为scope调用了zx_object_set_cookie()，或者cookie值尚未设置。

另见

object_get_cookie.