// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.sys2;

using fuchsia.component;
using fuchsia.io;

/// The maximum length of a storage instance ID.
/// A storage instance ID is a 128-bit UUID, which when encoded
/// in hex notation is 32 characters long.
const MAX_STORAGE_ID_LENGTH uint32 = 32;

@discoverable
protocol StorageAdmin {
    /// Opens the isolated directory for the given component. The open request will provision
    /// the storage if it hasn't been already.
    OpenComponentStorage(resource struct {
        relative_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        flags fuchsia.io.OpenFlags;
        mode uint32;
        object server_end:fuchsia.io.Node;
    });

    /// Lists the descendant components under the specified realm that use the storage
    /// capability.
    /// Returns INSTANCE_NOT_FOUND if the realm does not exist, and INVALID_ARGS if
    /// |relative_moniker| is malformed.
    ListStorageInRealm(resource struct {
        relative_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
        iterator server_end:StorageIterator;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Opens the isolated directory for the given storage ID. The open request will provision
    /// the storage if it hasn't been already.
    OpenComponentStorageById(resource struct {
        id string:MAX_STORAGE_ID_LENGTH;
        object server_end:fuchsia.io.Node;
    }) -> (struct {}) error fuchsia.component.Error;

    /// Deletes the contents of the storage for this component. Does not delete the component's
    /// subdirectory itself from the backing directory.
    DeleteComponentStorage(struct {
        relative_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;
    }) -> (struct {}) error fuchsia.component.Error;
};

/// An iterator protocol for returning a set of components using a storage capability. See
/// |StorageAdmin.ListStorageInRealm| for more information.
protocol StorageIterator {
    /// Retrieve the next set of components using the storage capability. The returned monikers
    /// are relative to the component that declares the storage capability. Returns an empty
    /// vector after all components have been returned.
    Next() -> (struct {
        relative_monikers vector<string:fuchsia.component.MAX_MONIKER_LENGTH>:MAX;
    });
};