// Copyright 2022 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.audio.device;

/// Use the `Provider` interface to manually add devices that do not use the devfs
/// mechanism. (Devices that use devfs are automatically added, upon detection.)
@discoverable
closed protocol Provider {
    strict AddDevice(resource table {
        /// The device's high-level name. Must not be an empty string.
        ///
        /// Required.
        1: device_name string:MAX_STRING_SIZE;

        /// Indicates the protocol used by the device, as well as (if StreamConfig) whether
        /// it is an input (a source of audio) or an output (a destination for audio).
        ///
        /// Required.
        2: device_type DeviceType;

        /// The client_end of the protocol channel (Codec, Composite, Dai or StreamConfig)
        /// that this service will use to configure/observe the device.
        /// For now, `AddDevice` only accepts a `codec_client`, `composite_client` or
        /// `stream_config_client` here.
        ///
        /// Required.
        /// # Deprecation
        ///
        /// Codec, Dai and StreamConfig are not supported anymore, instead use an
        /// [Audio Composite](https://fuchsia.dev/fuchsia-src/development/audio/drivers/composite)
        /// , see
        /// [Audio Drivers Architecture](https://fuchsia.dev/fuchsia-src/development/audio/drivers/architecture)
        @available(deprecated=HEAD)
        3: driver_client DriverClient;
    }) -> (table {}) error ProviderAddDeviceError;
};

/// Errors returned by the `Provider` protocol.
type ProviderAddDeviceError = flexible enum {
    /// The required `device_name` is incorrectly formed, empty or missing.
    INVALID_NAME = 1;

    /// The required `device_type` is missing.
    INVALID_TYPE = 2;

    /// The required `driver_client` is invalid or missing.
    INVALID_DRIVER_CLIENT = 3;

    /// The protocol in `driver_client` is incompatible with `device_type` or is not supported yet.
    WRONG_CLIENT_TYPE = 4;
};