/*
 * Copyright (C)2009 - SSHJ Contributors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package net.schmizz.sshj.connection.channel.direct;

import net.schmizz.sshj.connection.ConnectionException;
import net.schmizz.sshj.connection.channel.Channel;
import net.schmizz.sshj.transport.TransportException;

import java.io.InputStream;
import java.util.Map;

/**
 * A {@code session} channel provides for execution of a remote {@link Command command}, {@link Shell shell} or {@link
 * Subsystem subsystem}. Before this requests like starting X11 forwarding, setting environment variables, allocating a
 * PTY etc. can be made.
 * <p/>
 * It is not legal to reuse a {@code session} channel for more than one of command, shell, or subsystem. Once one of
 * these has been started this instance's API is invalid and that of the {@link Command specific} {@link Shell targets}
 * {@link Subsystem returned} should be used.
 *
 * @see Command
 * @see Shell
 * @see Subsystem
 */
public interface Session
        extends Channel {

    /** Command API. */
    interface Command
            extends Channel {

        /** Returns the command's {@code stderr} stream. */
        InputStream getErrorStream();

        /**
         * If the command exit violently {@link #getExitSignal() with a signal}, an error message would have been
         * received and can be retrieved via this method. Otherwise, this method will return {@code null}.
         * <p/>
         * <strong>NOTE: </strong> Always call {@link #close()} first before inspecting the exit error message.
         */
        String getExitErrorMessage();

        /**
         * Returns the {@link Signal signal} if the command exit violently, or {@code null} if this information was not
         * received.
         * <p/>
         * <strong>NOTE: </strong> Always call {@link #close()} first before inspecting the exit signal.
         */
        Signal getExitSignal();

        /**
         * Returns the exit status of the command if it was received, or {@code null} if this information was not
         * received.
         * <p/>
         * <strong>NOTE: </strong> Always call {@link #close()} first before inspecting the exit status.
         */
        Integer getExitStatus();

        /**
         * If the command exit violently {@link #getExitSignal() with a signal}, information about whether a core dump
         * took place would have been received and can be retrieved via this method. Otherwise, this method will return
         * {@code null}.
         */
        Boolean getExitWasCoreDumped();

        /**
         * Send a signal to the remote command.
         *
         * @param signal the signal
         *
         * @throws TransportException if error sending the signal
         */
        void signal(Signal signal)
                throws TransportException;

    }

    /** Shell API. */
    interface Shell
            extends Channel {

        /**
         * Whether the client can do local flow control using {@code control-S} and {@code control-Q}.
         *
         * @return boolean value indicating whether 'client can do', or {@code null} if no such information was
         *         received
         */
        Boolean canDoFlowControl();

        /**
         * Sends a window dimension change message.
         *
         * @param cols   terminal width, columns
         * @param rows   terminal height, rows
         * @param width  terminal width, pixels
         * @param height terminal height, pixels
         *
         * @throws TransportException
         */
        void changeWindowDimensions(int cols, int rows, int width, int height)
                throws TransportException;

        /** Returns the shell's {@code stderr} stream. */
        InputStream getErrorStream();

        /**
         * Send a signal.
         *
         * @param signal the signal
         *
         * @throws TransportException if error sending the signal
         */
        void signal(Signal signal)
                throws TransportException;

    }

    /** Subsystem API. */
    interface Subsystem
            extends Channel {

        Integer getExitStatus();
    }

    /**
     * Allocates a default PTY. The default PTY is {@code "vt100"} with the echo modes disabled.
     *
     * @throws net.schmizz.sshj.connection.ConnectionException
     *
     * @throws TransportException
     */
    void allocateDefaultPTY()
            throws ConnectionException, TransportException;

    /**
     * Allocate a psuedo-terminal for this session.
     * <p/>
     * {@code 0} dimension parameters will be ignored by the server.
     *
     * @param term   {@code TERM} environment variable value (e.g., {@code vt100})
     * @param cols   terminal width, cols (e.g., 80)
     * @param rows   terminal height, rows (e.g., 24)
     * @param width  terminal width, pixels (e.g., 640)
     * @param height terminal height, pixels (e.g., 480)
     * @param modes
     *
     * @throws ConnectionException
     * @throws TransportException
     */
    void allocatePTY(String term, int cols, int rows, int width, int height, Map<PTYMode, Integer> modes)
            throws ConnectionException, TransportException;

    /**
     * Execute a remote command.
     *
     * @param command
     *
     * @return {@link Command} instance which should now be used
     *
     * @throws ConnectionException if the request to execute the command failed
     * @throws TransportException  if there is an error sending the request
     */
    Command exec(String command)
            throws ConnectionException, TransportException;

    /**
     * Request X11 forwarding.
     *
     * @param authProto  X11 authentication protocol name
     * @param authCookie X11 authentication cookie
     * @param screen     X11 screen number
     *
     * @throws ConnectionException if the request failed
     * @throws TransportException  if there was an error sending the request
     */
    void reqX11Forwarding(String authProto, String authCookie, int screen)
            throws ConnectionException,
                   TransportException;

    /**
     * Set an environment variable.
     *
     * @param name  name of the variable
     * @param value value to set
     *
     * @throws ConnectionException if the request failed
     * @throws TransportException  if there was an error sending the request
     */
    void setEnvVar(String name, String value)
            throws ConnectionException, TransportException;

    /**
     * Request a shell.
     *
     * @return {@link Shell} instance which should now be used
     *
     * @throws ConnectionException if the request failed
     * @throws TransportException  if there was an error sending the request
     */
    Shell startShell()
            throws ConnectionException, TransportException;

    /**
     * Request a subsystem.
     *
     * @param name subsystem name
     *
     * @return {@link Subsystem} instance which should now be used
     *
     * @throws ConnectionException if the request failed
     * @throws TransportException  if there was an error sending the request
     */
    Subsystem startSubsystem(String name)
            throws ConnectionException, TransportException;

}
