Struct optee_utee::object::PersistentObject

pub struct PersistentObject(_);

An object identified by an Object Identifier and including a Data Stream.

Contrast TransientObject.

Implementations

impl PersistentObject

pub fn open(
    storage_id: ObjectStorageConstants,
    object_id: &[u8],
    flags: DataFlag
) -> Result<Self>

Open an existing PersistentObject.

Parameters

1. storage_id: The storaget to use which is defined in ObjectStorageConstants.
2. object_id: The object identifier. Note that this buffer cannot reside in shared memory.
3. flags: The DataFlag which determine the settings under which the object is opened.

Example

let obj_id = [1u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_READ) {
    Ok(object) =>
    {
        // ...
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

1. ItemNotFound: If the storage denoted by storage_id does not exist or if the object identifier cannot be found in the storage.
2. Access_Conflict: If an access right conflict was detected while opening the object.
3. OutOfMemory: If there is not enough memory to complete the operation.
4. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
5. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

Panics

1. If object_id.len() > MiscellaneousConstants::TeeObjectIdMaxLen
2. If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.

pub fn create(
    storage_id: ObjectStorageConstants,
    object_id: &[u8],
    flags: DataFlag,
    attributes: Option<ObjectHandle>,
    initial_data: &[u8]
) -> Result<Self>

Create a PersistentObject with initial attributes and an initial data stream content.

Parameters

1. storage_id: The storaget to use which is defined in ObjectStorageConstants.
2. object_id: The object identifier. Note that this buffer cannot reside in shared memory.
3. flags: The DataFlag which determine the settings under which the object is opened.
4. attributes: A handle on a PersistentObject or an initialized TransientObject from which to take the PersistentObject attributes. Can be NONE if the PersistentObject contains no attribute. For example,if it is a pure data object.

Example

let obj_id = [1u8;1];
let mut init_data: [u8; 0] = [0; 0];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_READ | DataFlag::ACCESS_WRITE
        None,
        &mut init_data) {
    Ok(object) =>
    {
        // ...
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

1. ItemNotFound: If the storage denoted by storage_id does not exist or if the object identifier cannot be found in the storage.
2. Access_Conflict: If an access right conflict was detected while opening the object.
3. OutOfMemory: If there is not enough memory to complete the operation.
4. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
5. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

Panics

1. If object_id.len() > MiscellaneousConstants::TeeObjectIdMaxLen.
2. If attributes is not NONE and is not a valid handle on an initialized object containing the type and attributes of the PersistentObject to create.
3. If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.

pub fn close_and_delete(&mut self) -> Result<()>

Marks an object for deletion and closes the object.

Example

let obj_id = [1u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_READ) {
    Ok(object) =>
    {
        object.close_and_delete()?;
        std::mem::forget(object);
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

1. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

Panics

1. If object is not a valid opened object.
2. If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.

pub fn rename(&mut self, new_object_id: &[u8]) -> Result<()>

Changes the identifier of an object. The object SHALL have been opened with the DataFlag::ACCESS_WRITE_META right, which means access to the object is exclusive.

Example

let obj_id = [1u8;1];
let new_obj_id = [2u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_WRITE_META) {
    Ok(object) =>
    {
        object.rename(&new_obj_id)?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

1. Access_Conflict: If an access right conflict was detected while opening the object.
2. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
3. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

Panics

1. If object is not a valid opened object.
2. If new_object_id resides in shared memory.
3. If new_object_id.len() > MiscellaneousConstants::TeeObjectIdMaxLen.
4. If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.

pub fn info(&self) -> Result<ObjectInfo>

Return the characteristics of an object. Function is similar to TransientObject::info besides extra errors.

Errors

1. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
2. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

pub fn restrict_usage(&mut self, obj_usage: UsageFlag) -> Result<()>

Restrict the object usage flags of an object handle to contain at most the flags passed in the obj_usage parameter. Function is similar to TransientObject::restrict_usage besides extra errors.

Errors

1. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
2. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

pub fn ref_attribute(&self, id: AttributeId, buffer: &mut [u8]) -> Result<usize>

Extract one buffer attribute from an object. The attribute is identified by the argument id. Function is similar to TransientObject::ref_attribute besides extra errors.

Errors

1. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
2. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

pub fn value_attribute(&self, id: u32) -> Result<(u32, u32)>

Extract one value attribute from an object. The attribute is identified by the argument id. Function is similar to TransientObject::value_attribute besides extra errors.

Errors

1. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
2. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

pub fn read(&self, buf: &mut [u8]) -> Result<u32>

Read requested size from the data stream assoicate with the object into the buffer.

Parameters

1. buffer: A pre-allocated buffer for saving the object’s data stream.
2. count: The returned value contains the number of bytes read.

Example

let obj_id = [1u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_READ) {
    Ok(object) =>
    {
        let read_buf = [0u8;16];
        object.read(&mut read_buf)?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

1. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
2. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

Panics

1. If object is not a valid opened object.
2. If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.

pub fn write(&mut self, buf: &[u8]) -> Result<()>

Write the passed in buffer data into from the data stream assoicate with the object.

Parameters

1. buffer: A pre-allocated buffer for saving the object’s data stream.

Example

let obj_id = [1u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_WRITE) {
    Ok(object) =>
    {
        let write_buf = [1u8;16];
        object.write(& write_buf)?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

1. StorageNoSpace: If insufficient storage space is available.
2. Overflow: If the value of the data position indicator resulting from this operation would be greater than MiscellaneousConstants::TeeDataMaxPosition.
3. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
4. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

Panics

1. If object is not a valid opened object.
2. If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.

pub fn truncate(&self, size: u32) -> Result<()>

Change the size of a data stream associate with the object.

Example

let obj_id = [1u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_WRITE) {
    Ok(object) =>
    {
        object.truncate(1u32)?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

1. StorageNoSpace: If insufficient storage space is available. would be greater than MiscellaneousConstants::TeeDataMaxPosition.
2. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
3. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

Panics

1. If object is not a valid opened object.
2. If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.

pub fn seek(&self, offset: i32, whence: Whence) -> Result<()>

Set the data position indicator associate with the object.

Parameters

1. whence: Defined in Whence.
2. offset: The bytes shifted based on whence.

Example

let obj_id = [1u8;1];
match PersistentObject::open(
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_WRITE) {
    Ok(object) =>
    {
        object.seek(0i32, Whence::DataSeekSet)?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

1. Overflow: If data position indicator is greater than MiscellaneousConstants::TeeDataMaxPosition.
2. CorruptObject: If the PersistentObject is corrupt. The object handle is closed.
3. StorageNotAvailable: If the PersistentObject is stored in a storage area which is currently inaccessible.

Panics

1. If object is not a valid opened object.
2. If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.

Trait Implementations

impl Drop for PersistentObject

fn drop(&mut self)

Close an opened PersistentObject.

Panics

1. If object is not a valid opened object.
2. If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.

impl ObjHandle for PersistentObject

fn handle(&self) -> TEE_ObjectHandle

Return the handle of an object.