optee_utee/object/enum_handle.rs
1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements. See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership. The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License. You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied. See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18use alloc::boxed::Box;
19
20use optee_utee_sys as raw;
21
22use super::ObjectInfo;
23use crate::{Error, Result, tee_check};
24
25// TODO: The examples and detailed function explanation will be added after we
26// test this struct and its functions.
27/// An enumerator for [PersistentObject](crate::PersistentObject)s.
28pub struct ObjectEnumHandle {
29 raw: *mut raw::TEE_ObjectEnumHandle,
30}
31
32impl ObjectEnumHandle {
33 /// Allocate an object enumerator.
34 /// Once an object enumerator has been allocated, it can be reused for
35 /// multiple enumerations.
36 pub fn allocate() -> Result<Self> {
37 let raw_handle: *mut raw::TEE_ObjectEnumHandle =
38 Box::into_raw(Box::new(core::ptr::null_mut()));
39 match unsafe { raw::TEE_AllocatePersistentObjectEnumerator(raw_handle) } {
40 raw::TEE_SUCCESS => Ok(Self { raw: raw_handle }),
41 code => {
42 unsafe {
43 drop(Box::from_raw(raw_handle));
44 }
45 Err(Error::from_raw_error(code))
46 }
47 }
48 }
49
50 /// Reset an object enumerator handle to its initial state after allocation.
51 /// If an enumeration has been started, it is stopped.
52 pub fn reset(&mut self) {
53 unsafe {
54 raw::TEE_ResetPersistentObjectEnumerator(*self.raw);
55 }
56 }
57
58 /// Start the enumeration of all the
59 /// [PersistentObject](crate::PersistentObject)s in a given Trusted Storage.
60 /// The object information can be retrieved by calling the function
61 /// [ObjectEnumHandle::get_next](crate::ObjectEnumHandle::get_next)
62 /// repeatedly.
63 pub fn start(&mut self, storage_id: u32) -> Result<()> {
64 tee_check(unsafe { raw::TEE_StartPersistentObjectEnumerator(*self.raw, storage_id) })
65 }
66
67 /// Get the next object in an enumeration and returns information about the
68 /// object: type, size, identifier, etc.
69 pub fn get_next(
70 &mut self,
71 object_info: Option<&mut ObjectInfo>,
72 object_id: &mut [u8],
73 ) -> Result<u32> {
74 let mut object_id_len = object_id.len();
75 let object_info = match object_info {
76 Some(a) => &mut a.raw,
77 None => core::ptr::null_mut(),
78 };
79 tee_check(unsafe {
80 raw::TEE_GetNextPersistentObject(
81 *self.raw,
82 object_info,
83 object_id.as_mut_ptr() as _,
84 &mut object_id_len,
85 )
86 })?;
87 Ok(object_id_len as u32)
88 }
89}
90
91impl Drop for ObjectEnumHandle {
92 /// Deallocates all resources associated with an object enumerator handle.
93 /// After this function is called, the handle is no longer valid.
94 ///
95 /// # Panics
96 ///
97 /// 1) If object is not a valid opened object.
98 /// 2) If the Implementation detects any other error.
99 fn drop(&mut self) {
100 unsafe {
101 raw::TEE_FreePersistentObjectEnumerator(*self.raw);
102 drop(Box::from_raw(self.raw));
103 }
104 }
105}