// Copyright 2019 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.
/// A PTY (pseudoterminal) emulates terminal devices, with a "server" side
/// (which represents the keyboard+monitor side of the terminal and is obtained
/// by opening /dev/misc/ptmx) and a number of "client" sides which are obtained
/// by calling `OpenClient`.
///
/// Client PTYs are identified by the `id` used in the `OpenClient` call. The
/// first Client PTY *must* be 0, and it is the only Client PTY that is allowed
/// to create additional Client PTYs, receive Events, etc. It is the
/// Controlling PTY.
@available(added=11)
library fuchsia.hardware.pty;

using fuchsia.io;
using fuchsia.unknown;
using zx;

/// When Feature Raw is enabled, OOB Events like ^c, ^z, etc are not generated.
/// Instead the character is read from the read() input path.
const FEATURE_RAW uint32 = 1;

type WindowSize = struct {
    width uint32;
    height uint32;
};

/// The terminal has no active client.
const EVENT_HANGUP uint32 = 1;
/// The terminal received a ^C control character.
const EVENT_INTERRUPT uint32 = 2;
/// The terminal received a ^Z control character.
const EVENT_SUSPEND uint32 = 4;
/// The terminal window has resized.
const EVENT_WINDOW_SIZE uint32 = 8;

/// All events
const EVENT_MASK uint32 = 15;

// TODO(https://fxbug.dev/42056856): Use a generated constant.
const DEVICE_PROTOCOL_NAME string = "fuchsia.hardware.pty/Device";

@discoverable
closed protocol Device {
    compose fuchsia.unknown.Cloneable;
    compose fuchsia.unknown.Closeable;
    compose fuchsia.unknown.Queryable;

    compose fuchsia.io.Readable;
    compose fuchsia.io.Writable;

    strict Describe() -> (resource table {
        /// An optional event which transmits information about a device's state.
        ///
        /// The [`DeviceSignal`] values may be observed on this event.
        1: event zx.Handle:EVENTPAIR;
    });

    /// Open a client PTY device with a unique `id`. `client` should be a handle
    /// to one endpoint of a channel that (on success) will become an open
    /// connection to the newly created device. On failure, the channel will be
    /// closed. Closing the channel will close the connection and release the
    /// device. If the provided `id` is 0, then the new client is a controlling
    /// client and has the capability to open additional clients. If the
    /// current device is not a controlling client, `ZX_ERR_ACCESS_DENIED` will be
    /// returned. If `id` is not unique, `ZX_ERR_INVALID_ARGS` will be returned.
    /// Otherwise the status code from `device_add` is passed on.
    strict OpenClient(resource struct {
        id uint32;
        client server_end:Device;
    }) -> (struct {
        s zx.Status;
    });

    /// allowed on Client PTYs
    /// -----------------------------
    /// Clear and/or Set PTY Features
    strict ClrSetFeature(struct {
        clr uint32;
        set uint32;
    }) -> (struct {
        status zx.Status;
        features uint32;
    });

    /// Obtain the window size (in character cells)
    strict GetWindowSize() -> (struct {
        status zx.Status;
        size WindowSize;
    });

    /// allowed on the Controlling PTY
    /// -------------------------------------
    /// Select which Client PTY receives input.
    /// Reads will simply block on non-active PTYs.
    strict MakeActive(struct {
        client_pty_id uint32;
    }) -> (struct {
        status zx.Status;
    });

    /// Returns pending OOB events, simultaneously clearing them
    strict ReadEvents() -> (struct {
        status zx.Status;
        events uint32;
    });

    /// allowed on the Server PTY
    /// --------------------------------
    /// Sets the window size
    strict SetWindowSize(struct {
        size WindowSize;
    }) -> (struct {
        status zx.Status;
    });
};