// 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=7)
library fuchsia.hardware.pty;

using fuchsia.device;
using fuchsia.io;
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;

/// When an event is pending, this signal is asserted on the Controlling PTY.
const SIGNAL_EVENT fuchsia.device.DeviceSignal = fuchsia.device.DeviceSignal.OOB;

@discoverable
protocol Device {
    // Compose from fuchsia.io.File so we can support Read/Write and export
    // a "Tty" type node info
    compose fuchsia.io.File;

    /// 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.
    OpenClient(resource struct {
        id uint32;
        client server_end:Device;
    }) -> (struct {
        s zx.status;
    });

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

    /// Obtain the window size (in character cells)
    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.
    MakeActive(struct {
        client_pty_id uint32;
    }) -> (struct {
        status zx.status;
    });

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

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