<reference>
    <title>@PACKAGE@ - Version @VERSION@</title>
    <partintro>
        <title>Packages</title>

        <para>The various source and binary packages are available at <ulink
        url="http://www.five-ten-sg.com/@PACKAGE@/packages/">http://www.five-ten-sg.com/@PACKAGE@/packages/</ulink>.
        The most recent documentation is available at <ulink
        url="http://www.five-ten-sg.com/@PACKAGE@/">http://www.five-ten-sg.com/@PACKAGE@/</ulink>.
        </para>

        <para>A <ulink
        url="http://www.selenic.com/mercurial/wiki/">Mercurial</ulink> source
        code repository for this project is available at <ulink
        url="http://hg.five-ten-sg.com/@PACKAGE@/">http://hg.five-ten-sg.com/@PACKAGE@/</ulink>.
        </para>

    </partintro>

    <refentry id="x@PACKAGE@.1">
        <refentryinfo>
            <date>2015-05-01</date>
            <author>
                <firstname>Carl</firstname>
                <surname>Byington</surname>
                <affiliation><orgname>510 Software Group</orgname></affiliation>
            </author>
        </refentryinfo>

        <refmeta>
            <refentrytitle>@PACKAGE@</refentrytitle>
            <manvolnum>1</manvolnum>
            <refmiscinfo>@PACKAGE@ @VERSION@</refmiscinfo>
        </refmeta>

        <refnamediv id='name.1'>
            <refname>@PACKAGE@</refname>
            <refpurpose>a monitoring package for the android terminal emulator</refpurpose>
        </refnamediv>

        <refsect1 id='build.1'>
            <title>Build method</title>
            <para>
                This is an android project with no native code, so
                "android update project -p . -t android-16; ant debug"
                should build cleanly.
            </para>
        </refsect1>

        <refsect1 id='introduction.1'>
            <title>Introduction</title>
            <para>
                This is a stub monitoring application for the related
                510 Connectbot android terminal emulator package.
            </para>
        </refsect1>

        <refsect1 id='monitor.1'>
            <title>Terminal Monitor</title>
            <para>
                For every terminal session (local, telnet, ssh or tn5250), the
                terminal emulator also makes a connection to a terminal monitor
                process, which can see cursor movement and screen contents, and can
                inject characters to send to the host.
            </para>

            <para>
                The terminal monitor is invoked by calling an android Intent
                named "com.five_ten_sg.connectbot.monitor.MonitorService". That
                ensures that the monitor process is running, and should then
                be listening on TCP port 6000 for incoming connections. The terminal
                emulator then connects to the terminal monitor on port 6000.
                The native android Intent and Service communication mechanisms
                are not used.
            </para>

            <para>
                The messages exchanged between the terminal emulator and the
                terminal monitor are arrays of uint16 values in network byte
                order. Each message starts with a uint16 message byte length,
                followed by that many bytes of data. Note that the message length
                will always be even. The next uint16 contains the message
                command value, and the remaining uint16 values are the arguments
                if any for that command.
            </para>

            <para>
                Any arguments that are keystrokes or characters are represented
                as 16 bit unicode. Note that the first 256 such characters are
                identical to the ISO-8859-1 latin character set.
            </para>

            <para>
                INIT = 0 (TE -> Monitor). The argument is a string of uint16
                characters. The meaning of these characters is defined by the
                monitor. It might be a fully qualified path name, or some other
                data used by the monitor to drive the monitoring of this
                connection.
            </para>

            <para>
                ACTIVATE = 1 (TE -> Monitor).  The first argument is the
                number of lines. The second argument is the number of columns.
                That is followed by lines*columns uint16 character codes for
                the current screen contents.
                This connection is now the active connection. It is the
                topmost (or only) window visible to the user - typed keystrokes
                will be sent to the host on the other end of this connection.
            </para>

            <para>
                KEYSTATE = 2 (TE -> Monitor). The argument is a single uint16
                value, 1 for key down, 0 for key up. The TE tracks a single special
                key for the monitor, and reports key up/down state when it changes.
                The actual key should be configurable.
            </para>

            <para>
                CURSORMOVE = 3 (TE -> Monitor).
                The first argument is the line number (0..23),
                the second argument is the column number (0..79), and the third
                argument is the reason for sending this cursor update. REASON=0 is
                from a previous CURSORREQUEST command. REASON=1 is a cursor update
                related to the previous SCREENCHANGE buffer update. REASON=2 is
                a cursor update caused by user keystrokes.
            </para>

            <para>
                SCREENCHANGE = 4 (TE -> Monitor). The first argument is the
                number of lines. The second argument is the number of columns.
                That is followed by lines*columns uint16 character codes for
                the current screen contents.
            </para>

            <para>
                FIELDVALUE = 5 (TE -> Monitor).
                SETFIELD = 5 (Monitor -> TE).
                The first argument is the line number (0..23)
                and the second argument is the column number (0..79).
                That is followed by the field value, a sequence of uint16
                character codes from the screen buffer. The field
                covers N columns, where N = (message length - 4) / 2.
                When sent from the monitor to the emulator, this causes
                the emulator to send the field codes to the host (for async
                modes) or to set the specified field contents (for block modes).
                This is also used as the reply message from the emulator to the
                monitor for a previous GETFIELD from the monitor.
            </para>

            <para>
                GETFIELD = 6 (Monitor -> TE).
                The first argument is the line number (0..23)
                and the second argument is the starting column number (0..79),
                and the third argument is the field length in columns.
                This command causes the emulator to send a FIELDVALUE message
                back to the monitor.
            </para>

            <para>
                SCREENWATCH = 7 (Monitor -> TE).
                The first argument is the line number (0..23)
                and the second argument is the starting column number (0..79),
                and the third argument is the field length in columns.
                This command causes the emulator to watch the specified
                part of the screen for changes. When that part of the screen
                changes, the emulator will send a SCREENCHANGE message back
                to the monitor. The initial screen watch area is the entire
                screen.
            </para>

            <para>
                DEPRESS = 8 (Monitor -> TE). The argument is a single uint16
                value containing the vk_key value. This command causes the emulator
                to simulate a keypress for that key. The codes are defined
                <ulink url="http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731">here</ulink>.
            </para>

            <para>
                SHOWURL = 9 (Monitor -> TE). The single argument is a sequence
                of uint16 character codes forming a URL to be displayed.
            </para>

            <para>
                SWITCHSESSION = 10 (Monitor -> TE). There are no arguments. The TE
                should display this session.
            </para>

            <para>
                CURSORREQUEST = 11 (Monitor -> TE). There are no arguments. The TE
                should send a CURSORMOVE update to the monitor. Cursor movement caused
                by SETFIELD or DEPRESS commands does not trigger CURSORMOVE updates
                in block mode (tn5250) sessions. Those commands do trigger CURSORMOVE
                updates in async mode (telnet, ssh) sessions.
            </para>
        </refsect1>

        <refsect1 id='synchronization.1'>
            <title>Synchronization issues</title>
            <para>
                The terminal emulator should delay sending CURSORMOVE and SCREENCHANGE
                messages until the socket has been quiet for 10 milliseconds or until
                the 5250 block mode terminal keyboard has been unlocked by the host.
                The monitor might send SETFIELD or DEPRESS messages in response to
                those CURSORMOVE or SCREENCHANGE messages. If the 5250 block mode
                keyboard is locked, the terminal emulator should buffer those keystrokes
                and send them when the keyboard unlocks.
            </para>
        </refsect1>

        <refsect1 id='todo.1'>
            <title>TODO</title>
            <para>
                Nothing.
            </para>
        </refsect1>

        <refsect1 id='copyright.1'>
            <title>Copyright</title>
            <para>
                Copyright (C) 2014 by 510 Software Group &lt;carl@five-ten-sg.com&gt;
            </para>
            <para>
                This program is free software; you can redistribute it and/or modify it
                under the terms of the GNU General Public License as published by the
                Free Software Foundation; either version 3, or (at your option) any
                later version.
            </para>
            <para>
                You should have received a copy of the GNU General Public License along
                with this program; see the file COPYING.  If not, please write to the
                Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
            </para>
        </refsect1>

        <refsect1 id='version.1'>
            <title>Version</title>
            <para>
                @VERSION@
            </para>
        </refsect1>
    </refentry>

</reference>