blob: 7e23e284930978b648fdd2476987d6cef9e0f3e2 [file] [log] [blame] [edit]
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#pragma once
#include <stdint.h>
#include <interface/storage/storage.h>
#include <lk/compiler.h>
#include <uapi/trusty_uuid.h>
#include "client_session.h"
#include "file.h"
/**
* struct storage_op_flags - Flags shared by all storage operations
* @allow_repaired: If true, encountering a repaired filesystem will _not_
* result in an error.
* @complete_transaction: If true, complete the currently active transaction
* after performing this operation.
* @update_checkpoint: If true, update the checkpoint with the post-operation
* filesystem state.
*/
struct storage_op_flags {
bool allow_repaired;
bool complete_transaction;
bool update_checkpoint;
};
__BEGIN_CDECLS
/**
* storage_client_session_init() - Initialize a new &struct
* storage_client_session.
* @session: The session to be initialized.
* @fs: The filesystem this session will modify.
* @peer: Id of the peer this session was created for.
*/
void storage_client_session_init(struct storage_client_session* session,
struct fs* fs,
const uuid_t* peer);
/**
* storage_client_session_destroy() - Destroy a &struct storage_client_session.
* @session: The session to be destroyed.
*/
void storage_client_session_destroy(struct storage_client_session* session);
/**
* storage_transaction_end() - End the currently active transaction and start a
* new one. If @flags.complete_transaction is true, try to complete the current
* transaction. Otherwise, abandon it.
* @session: The session to perform the operation.
* @flags: Flags for performing this operation. @flags.complete_transaction
* controls whether the transaction will be completed or abandoned; see above.
* See &struct storage_op_flags for further details.
*/
enum storage_err storage_transaction_end(struct storage_client_session* session,
struct storage_op_flags flags);
/**
* storage_file_delete() - Delete a file.
* @session: The session to perform the operation.
* @fname: The string containing the name of the file to be deleted.
* @fname_len: The length of the name of the file to be deleted.
* @flags: Flags for performing this operation. See &struct storage_op_flags for
* details.
*/
enum storage_err storage_file_delete(struct storage_client_session* session,
const char* fname,
size_t fname_len,
struct storage_op_flags flags);
/**
* storage_file_move() - Move a file from ``src`` to location ``dst``.
* @session: The session to perform the operation.
* @handle: The opened file handle for the ``src`` file. Ignored if
* @src_already_opened is false.
* @src_already_opened: True if the ``src`` file is already opened and @handle
* conatins its file handle.
* @src_name: The string containing the name of the ``src`` file. If
* @src_already_opened is true, this must match the name of the file @handle
* points to or be null.
* @src_name_len: The length of the @src_name.
* @dst_name: The string containing the name of the file's destination.
* @dst_name_len: The length of @dst_name.
* @dst_file_create_mode: Creation behavior for the ``dst`` file.
* @flags: Flags for performing this operation. See &struct storage_op_flags for
* details.
*/
enum storage_err storage_file_move(struct storage_client_session* session,
uint32_t handle,
bool src_already_opened,
const char* src_name,
size_t src_name_len,
const char* dst_name,
size_t dst_name_len,
enum file_create_mode dst_file_create_mode,
struct storage_op_flags flags);
/**
* storage_file_open() - Open a file and provide a handle to it.
* @session: The session to perform the operation.
* @fname: The string containing the name of the file to open.
* @fname_len: The length of the name of the file to open.
* @file_create_mode: Creation behavior for the file.
* @truncate: If true, clear the file's contents while opening it.
* @flags: Flags for performing this operation. See &struct storage_op_flags for
* details.
* @handle: Out-param that will contain the opened file's handle. Only populated
* on success.
*/
enum storage_err storage_file_open(struct storage_client_session* session,
const char* fname,
size_t fname_len,
enum file_create_mode file_create_mode,
bool truncate,
struct storage_op_flags flags,
uint32_t* handle);
/**
* storage_file_close() - Close a previously opened file.
* @session: The session to perform the operation.
* @handle: The file handle previously created by storage_file_open().
* @flags: Flags for performing this operation. See &struct storage_op_flags for
* details.
*/
enum storage_err storage_file_close(struct storage_client_session* session,
uint32_t handle,
struct storage_op_flags flags);
/**
* storage_file_read() - Read a sequence of bytes from an open file.
* @session: The session to perform the operation.
* @handle: The file handle previously created by storage_file_open().
* @size: The size of the byte sequence to read.
* @offset: The offset from the beginning of the file at which to start reading.
* The bytes read will be ``file[offset..offset + size]``.
* @flags: Flags for performing this operation. See &struct storage_op_flags for
* details.
* @resp: Out-param. The buffer into which the read bytes will be written.
* @resp_len: Before the calling ``*resp_len`` should contain the length of the
* &resp buffer. After a successful call returns, ``*resp_len`` will contain the
* total number of bytes written to &resp.
*/
enum storage_err storage_file_read(struct storage_client_session* session,
uint32_t handle,
uint32_t size,
uint64_t offset,
struct storage_op_flags flags,
uint8_t* resp,
size_t* resp_len);
/**
* storage_file_write() - Write a sequence of bytes to an open file.
* @session: The session to perform the operation.
* @handle: The file handle previously created by storage_file_open().
* @offset: The offset from the beginning of the file at which to start writing.
* The bytes will be written to ``file[offset..offset + data.len]``.
* @data: Buffer containing the data to write.
* @data_len: Length of the data to write, in bytes.
* @flags: Flags for performing this operation. See &struct storage_op_flags for
* details.
*/
enum storage_err storage_file_write(struct storage_client_session* session,
uint32_t handle,
uint64_t offset,
const uint8_t* data,
size_t data_len,
struct storage_op_flags flags);
/**
* storage_file_list() - Lists the names of files.
* @session: The session to perform the operation.
* @max_count: The maximum number of file path entries to be recorded with
* @record_path.
* @last_state: Either %STORAGE_FILE_LIST_START or the @flags arg of the last
* call to @record_path during the previous call to storage_file_list().
* @last_fname: Ignored if @last_state is %STORAGE_FILE_LIST_START. Otherwise,
* @last_fname should contain the @path arg of the last call to @record_path
* during the previous call to storage_file_list().
* @last_fname_len: The length of @last_fname if @last_fname is present. Ignored
* otherwise.
* @flags: Flags for performing this operation. See &struct storage_op_flags for
* details.
* @can_record_path: Checks whether a path (with a length less than or equal to
* @can_record_path.max_path_len) can be recorded using the @record_path
* callback.
* @record_path: Records a @record_path.path that is @record_path.path_len bytes
* long. @record_path.path may be null if @record_path.flags is
* %STORAGE_FILE_LIST_END.
* @callback_data: Will be passed as the first argument to calls to
* @can_record_path and @record_path.
*/
enum storage_err storage_file_list(
struct storage_client_session* session,
uint8_t max_count,
enum storage_file_list_flag last_state,
const char* last_fname,
size_t last_fname_len,
struct storage_op_flags flags,
bool (*can_record_path)(void* callback_data, size_t max_path_len),
void (*record_path)(void* callback_data,
enum storage_file_list_flag flags,
const char* path,
size_t path_len),
void* callback_data);
/**
* storage_file_get_size() - Gets the size of a file.
* @session: The session to perform the operation.
* @handle: The file handle previously created by storage_file_open().
* @flags: Flags for performing this operation. See &struct storage_op_flags for
* details.
* @size: Out-param. After a successful call, contains the file's size.
*/
enum storage_err storage_file_get_size(struct storage_client_session* session,
uint32_t handle,
struct storage_op_flags flags,
uint64_t* size);
/**
* storage_file_set_size() - Sets the size of a file. Truncates if the file is
* larger than @new_size.
* @session: The session to perform the operation.
* @handle: The file handle previously created by storage_file_open().
* @new_size: The file's target size.
* @flags: Flags for performing this operation. See &struct storage_op_flags for
* details.
*/
enum storage_err storage_file_set_size(struct storage_client_session* session,
uint32_t handle,
uint64_t new_size,
struct storage_op_flags flags);
__END_CDECLS