zx_object_get_cookie

英文原文快照

名称

object_get_cookie —— 获取对象的cookie值。

概要

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

描述

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

如果已在对象上设置了cookie的值，则可以使用与scope相同的对象来调用zx_object_get_cookie() 以获取cookie。

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

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

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

权限

TODO(ZX-2399)

返回值

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

错误码

ZX_ERR_BAD_HANDLE：handle或scope是无效句柄。

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

ZX_ERR_ACCESS_DENIED：cookie值尚未设置，或者scope不是获取已设置的cookie值的正确范围 。

ZX_ERR_INVALID_ARGS：cookie是无效指针。

另见

object_set_cookie.