// 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.driver.index;

using fuchsia.driver.development;
using fuchsia.url;
using zx;

/// Protocol for driver development APIs for the driver index.
/// This interface should only be used for development and disabled in release builds.
/// This protocol is internal to the driver framework and should not be used directly by users.
/// Users should go through the `fuchsia.driver.development/Manager` protocol instead.
@discoverable
closed protocol DevelopmentManager {
    /// Returns a list of all drivers that are known to the system.
    /// If a |driver_filter| is provided, the returned list will be filtered to
    /// only include drivers specified in the filter.
    ///
    /// |iterator| is closed with following epitaphs on error:
    /// ZX_ERR_NOT_FOUND indicates that there is no driver matching the given path for at least
    /// one driver in |driver_filter|.
    /// ZX_ERR_BUFFER_TOO_SMALL indicates that the driver's bind program is longer than the
    /// maximum number of instructions (BIND_PROGRAM_INSTRUCTIONS_MAX).
    strict GetDriverInfo(resource struct {
        driver_filter vector<string:MAX>:MAX;
        iterator server_end:fuchsia.driver.development.DriverInfoIterator;
    });

    /// Returns a list of all composite node specs that are known to the system.
    /// If a |name_filter| is provided, the returned list will only include 1 spec,
    /// the one with that exact name.
    ///
    /// |iterator| is closed with following epitaphs on error:
    /// ZX_ERR_NOT_FOUND indicates that there are no specs or if a |name_filter| is provided,
    /// that there are no specs with that name.
    strict GetCompositeNodeSpecs(resource struct {
        name_filter string:<MAX, optional>;
        iterator server_end:fuchsia.driver.development.CompositeNodeSpecIterator;
    });

    /// Disables the driver with the given driver component url.
    /// Disabled drivers will not be considered for matching to nodes.
    /// If a |package_hash| is provided, only that specific version of the driver
    /// package will be disabled. Otherwise this applies to all existing versions
    /// of a driver with the given url.
    /// Returns an error ZX_ERR_NOT_FOUND if no drivers were affected.
    strict DisableDriver(struct {
        driver_url fuchsia.url.Url;
        package_hash string:<fuchsia.driver.development.HASH_LENGTH, optional>;
    }) -> () error zx.Status;

    /// Enables the driver with the given driver component url.
    /// This is only meant to revert a |DisableDriver| action.
    /// Returns an error ZX_ERR_NOT_FOUND if no drivers were affected.
    strict EnableDriver(struct {
        driver_url fuchsia.url.Url;
        package_hash string:<fuchsia.driver.development.HASH_LENGTH, optional>;
    }) -> () error zx.Status;
};