pub struct PersistentObject(/* private fields */);Expand description
An object identified by an Object Identifier and including a Data Stream.
Contrast TransientObject.
Implementations§
Source§impl PersistentObject
impl PersistentObject
Sourcepub fn open(
storage_id: ObjectStorageConstants,
object_id: &[u8],
flags: DataFlag,
) -> Result<Self>
pub fn open( storage_id: ObjectStorageConstants, object_id: &[u8], flags: DataFlag, ) -> Result<Self>
Open an existing persistent object.
§Parameters
storage_id: The storage to use which is defined in ObjectStorageConstants.object_id: The object identifier. Note that this buffer cannot reside in shared memory.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
ItemNotFound: If the storage denoted by storage_id does not exist or if the object identifier cannot be found in the storage.Access_Conflict: If an access right conflict was detected while opening the object.OutOfMemory: If there is not enough memory to complete the operation.CorruptObject: If the object is corrupt. The object handle SHALL behave based on thegpd.ta.doesNotCloseHandleOnCorruptObjectproperty.StorageNotAvailable: If the object is stored in a storage area which is currently inaccessible.
§Panics
- If object_id.len() > MiscellaneousConstants::TeeObjectIdMaxLen
- If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.
Sourcepub fn create(
storage_id: ObjectStorageConstants,
object_id: &[u8],
flags: DataFlag,
attributes: Option<ObjectHandle>,
initial_data: &[u8],
) -> Result<Self>
pub fn create( storage_id: ObjectStorageConstants, object_id: &[u8], flags: DataFlag, attributes: Option<ObjectHandle>, initial_data: &[u8], ) -> Result<Self>
Create an object with initial attributes and an initial data stream content.
§Parameters
storage_id: The storage to use which is defined in ObjectStorageConstants.object_id: The object identifier. Note that this buffer cannot reside in shared memory.flags: The DataFlag which determine the settings under which the object is opened.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::create(
ObjectStorageConstants::Private,
&obj_id,
DataFlag::ACCESS_READ | DataFlag::ACCESS_WRITE,
None,
&mut init_data) {
Ok(object) =>
{
// ...
Ok(())
}
Err(e) => Err(e),
}§Errors
ItemNotFound: If the storage denoted by storage_id does not exist.Access_Conflict: If an access right conflict was detected while opening the object.OutOfMemory: If there is not enough memory to complete the operation.StorageNoSpace: If insufficient space is available to create the persistent object.CorruptObject: If the storage is corrupt.StorageNotAvailable: If the object is stored in a storage area which is currently inaccessible.
§Panics
- If object_id.len() > MiscellaneousConstants::TeeObjectIdMaxLen.
- If attributes is not NONE and is not a valid handle on an initialized object containing the type and attributes of the object to create.
- If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.
Sourcepub fn close_and_delete(self) -> Result<()>
pub fn close_and_delete(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(mut object) =>
{
object.close_and_delete()?;
Ok(())
}
Err(e) => Err(e),
}§Errors
StorageNotAvailable: If the object is stored in a storage area which is currently inaccessible.
§Panics
- If object is not a valid opened object.
- If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.
§Breaking Changes
Now we no longer need to call core::mem::forget after successfully calling
close_and_delete, and code like this will now produce a compilation error.
let mut obj = PersistentObject::open (
ObjectStorageConstants::Private,
&obj_id,
DataFlag::ACCESS_READ,
)?;
obj.close_and_delete()?;
core::mem::forget(obj); // will get compilation error in this line
// ^^^ value used here after moveSourcepub fn rename(&mut self, new_object_id: &[u8]) -> Result<()>
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(mut object) =>
{
object.rename(&new_obj_id)?;
Ok(())
}
Err(e) => Err(e),
}§Errors
AccessConflict: If an object with the same identifier already exists.CorruptObject: If the object is corrupt. The object handle SHALL behave based on thegpd.ta.doesNotCloseHandleOnCorruptObjectproperty.StorageNotAvailable: If the object is stored in a storage area which is currently inaccessible.
§Panics
- If object is not a valid handle on a persistent object that has been opened with the write-meta access right.
- If new_object_id resides in shared memory.
- If new_object_id.len() > MiscellaneousConstants::TeeObjectIdMaxLen.
- If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.
Sourcepub fn read(&mut self, buf: &mut [u8]) -> Result<u32>
pub fn read(&mut self, buf: &mut [u8]) -> Result<u32>
Read requested size from the data stream associate with the object into the buffer.
§Parameters
buffer: A pre-allocated TA-private buffer for saving the object’s data stream. Client-shared memory must not be passed here; useSelf::read_remaining_to_vecand copy the result to the client instead.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(mut object) =>
{
let mut read_buf = [0u8;16];
object.read(&mut read_buf)?;
Ok(())
}
Err(e) => Err(e),
}§Errors
CorruptObject: If the object is corrupt. The object handle SHALL behave based on thegpd.ta.doesNotCloseHandleOnCorruptObjectproperty.StorageNotAvailable: If the object is stored in a storage area which is currently inaccessible.
§Panics
- If object is not a valid handle on a persistent object opened with the read access right.
- If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.
Sourcepub fn read_remaining_to_vec(&mut self) -> Result<Vec<u8>>
pub fn read_remaining_to_vec(&mut self) -> Result<Vec<u8>>
Reads the remaining data from the current cursor into a new TA-private vector.
This method does not rewind the cursor. To read the entire object, first
call seek(0, Whence::DataSeekSet).
The allocation is sized using the object’s current metadata. The returned vector contains only the bytes actually read, and the data position advances accordingly. At or beyond the end of the object, returns an empty vector. Concurrent growth after the metadata query is not included in this read.
Returns errors from GenericObject::info or Self::read, or
ErrorKind::OutOfMemory if the allocation fails.
Sourcepub fn write(&mut self, buf: &[u8]) -> Result<()>
pub fn write(&mut self, buf: &[u8]) -> Result<()>
Write the passed in buffer data into from the data stream associate with the object.
§Parameters
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(mut object) =>
{
let write_buf = [1u8;16];
object.write(& write_buf)?;
Ok(())
}
Err(e) => Err(e),
}§Errors
StorageNoSpace: If insufficient storage space is available.Overflow: If the value of the data position indicator resulting from this operation would be greater than MiscellaneousConstants::TeeDataMaxPosition.CorruptObject: If the object is corrupt. The object handle SHALL behave based on thegpd.ta.doesNotCloseHandleOnCorruptObjectproperty.StorageNotAvailable: If the object is stored in a storage area which is currently inaccessible.
§Panics
- If object is not a valid handle on a persistent object opened with the write access right
- If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.
Sourcepub fn truncate(&mut self, size: u32) -> Result<()>
pub fn truncate(&mut 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(mut object) =>
{
object.truncate(1u32)?;
Ok(())
}
Err(e) => Err(e),
}§Errors
StorageNoSpace: If insufficient storage space is available.CorruptObject: If the object is corrupt. The object handle SHALL behave based on thegpd.ta.doesNotCloseHandleOnCorruptObjectproperty.StorageNotAvailable: If the object is stored in a storage area which is currently inaccessible.
§Panics
- If object is not a valid handle on a persistent object opened with the write access right.
- If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.
Sourcepub fn seek(&mut self, offset: i32, whence: Whence) -> Result<()>
pub fn seek(&mut self, offset: i32, whence: Whence) -> Result<()>
Set the data position indicator associate with the object.
§Parameters
whence: Defined in Whence.offset: The bytes shifted based onwhence.
§Example
let obj_id = [1u8;1];
match PersistentObject::open(
ObjectStorageConstants::Private,
&obj_id,
DataFlag::ACCESS_WRITE) {
Ok(mut object) =>
{
object.seek(0i32, Whence::DataSeekSet)?;
Ok(())
}
Err(e) => Err(e),
}§Errors
Overflow: If data position indicator is greater than MiscellaneousConstants::TeeDataMaxPosition.CorruptObject: If the object is corrupt. The object handle SHALL behave based on thegpd.ta.doesNotCloseHandleOnCorruptObjectproperty.StorageNotAvailable: If the object is stored in a storage area which is currently inaccessible.
§Panics
- If object is not a valid handle on a persistent object.
- If the Implementation detects any other error associated with this function which is not explicitly associated with a defined return code for this function.