Upgrade libgit2

[TortoiseGit.git] / src / TortoisePlink / PUTTY.H

#ifndef PUTTY_PUTTY_H\r
#define PUTTY_PUTTY_H\r
\r
#include <stddef.h>                    /* for wchar_t */\r
#include <limits.h>                    /* for INT_MAX */\r
\r
#include "defs.h"\r
#include "platform.h"\r
#include "network.h"\r
#include "misc.h"\r
#include "marshal.h"\r
\r
/*\r
 * We express various time intervals in unsigned long minutes, but may need to\r
 * clip some values so that the resulting number of ticks does not overflow an\r
 * integer value.\r
 */\r
#define MAX_TICK_MINS   (INT_MAX / (60 * TICKSPERSEC))\r
\r
/*\r
 * Fingerprints of the current and previous PGP master keys, to\r
 * establish a trust path between an executable and other files.\r
 */\r
#define PGP_MASTER_KEY_YEAR "2023"\r
#define PGP_MASTER_KEY_DETAILS "RSA, 4096-bit"\r
#define PGP_MASTER_KEY_FP                                  \\r
    "28D4 7C46 55E7 65A6 D827  AC66 B15D 9EFC 216B 06A1"\r
#define PGP_PREV_MASTER_KEY_YEAR "2021"\r
#define PGP_PREV_MASTER_KEY_DETAILS "RSA, 3072-bit"\r
#define PGP_PREV_MASTER_KEY_FP                                  \\r
    "A872 D42F 1660 890F 0E05  223E DD43 55EA AC11 19DE"\r
\r
/*\r
 * Definitions of three separate indexing schemes for colour palette\r
 * entries.\r
 *\r
 * Why three? Because history, sorry.\r
 *\r
 * Two of the colour indexings are used in escape sequences. The\r
 * Linux-console style OSC P sequences for setting the palette use an\r
 * indexing in which the eight standard ANSI SGR colours come first,\r
 * then their bold versions, and then six extra colours for default\r
 * fg/bg and the terminal cursor. And the xterm OSC 4 sequences for\r
 * querying the palette use a related indexing in which the six extra\r
 * colours are pushed up to indices 256 and onwards, with the previous\r
 * 16 being the first part of the xterm 256-colour space, and 240\r
 * additional terminal-accessible colours inserted in the middle.\r
 *\r
 * The third indexing is the order that the colours appear in the\r
 * PuTTY configuration panel, and also the order in which they're\r
 * described in the saved session files. This order specifies the same\r
 * set of colours as the OSC P encoding, but in a different order,\r
 * with the default fg/bg colours (which users are most likely to want\r
 * to reconfigure) at the start, and the ANSI SGR colours coming\r
 * later.\r
 *\r
 * So all three indices really are needed, because all three appear in\r
 * protocols or file formats outside the PuTTY binary. (Changing the\r
 * saved-session encoding would have a backwards-compatibility impact;\r
 * also, if we ever do, it would be better to replace the numeric\r
 * indices with descriptive keywords.)\r
 *\r
 * Since the OSC 4 encoding contains the full set of colours used in\r
 * the terminal display, that's the encoding used by front ends to\r
 * store any actual data associated with their palette entries. So the\r
 * TermWin palette_set and palette_get_overrides methods use that\r
 * encoding, and so does the bitwise encoding of attribute words used\r
 * in terminal redraw operations.\r
 *\r
 * The Conf encoding, of course, is used by config.c and settings.c.\r
 *\r
 * The aim is that those two sections of the code should never need to\r
 * come directly into contact, and the only module that should have to\r
 * deal directly with the mapping between these colour encodings - or\r
 * to deal _at all_ with the intermediate OSC P encoding - is\r
 * terminal.c itself.\r
 */\r
\r
#define CONF_NCOLOURS 22               /* 16 + 6 special ones */\r
#define OSCP_NCOLOURS 22               /* same as CONF, but different order */\r
#define OSC4_NCOLOURS 262              /* 256 + the same 6 special ones */\r
\r
/* The list macro for the conf colours also gives the textual names\r
 * used in the GUI configurer */\r
#define CONF_COLOUR_LIST(X)                     \\r
    X(fg, "Default Foreground")                 \\r
    X(fg_bold, "Default Bold Foreground")       \\r
    X(bg, "Default Background")                 \\r
    X(bg_bold, "Default Bold Background")       \\r
    X(cursor_fg, "Cursor Text")                 \\r
    X(cursor_bg, "Cursor Colour")               \\r
    X(black, "ANSI Black")                      \\r
    X(black_bold, "ANSI Black Bold")            \\r
    X(red, "ANSI Red")                          \\r
    X(red_bold, "ANSI Red Bold")                \\r
    X(green, "ANSI Green")                      \\r
    X(green_bold, "ANSI Green Bold")            \\r
    X(yellow, "ANSI Yellow")                    \\r
    X(yellow_bold, "ANSI Yellow Bold")          \\r
    X(blue, "ANSI Blue")                        \\r
    X(blue_bold, "ANSI Blue Bold")              \\r
    X(magenta, "ANSI Magenta")                  \\r
    X(magenta_bold, "ANSI Magenta Bold")        \\r
    X(cyan, "ANSI Cyan")                        \\r
    X(cyan_bold, "ANSI Cyan Bold")              \\r
    X(white, "ANSI White")                      \\r
    X(white_bold, "ANSI White Bold")            \\r
    /* end of list */\r
\r
#define OSCP_COLOUR_LIST(X)                     \\r
    X(black)                                    \\r
    X(red)                                      \\r
    X(green)                                    \\r
    X(yellow)                                   \\r
    X(blue)                                     \\r
    X(magenta)                                  \\r
    X(cyan)                                     \\r
    X(white)                                    \\r
    X(black_bold)                               \\r
    X(red_bold)                                 \\r
    X(green_bold)                               \\r
    X(yellow_bold)                              \\r
    X(blue_bold)                                \\r
    X(magenta_bold)                             \\r
    X(cyan_bold)                                \\r
    X(white_bold)                               \\r
    /*\r
     * In the OSC 4 indexing, this is where the extra 240 colours go.\r
     * They consist of:\r
     *\r
     *  - 216 colours forming a 6x6x6 cube, with R the most\r
     *    significant colour and G the least. In other words, these\r
     *    occupy the space of indices 16 <= i < 232, with each\r
     *    individual colour found as i = 16 + 36*r + 6*g + b, for all\r
     *    0 <= r,g,b <= 5.\r
     *\r
     *  - The remaining indices, 232 <= i < 256, consist of a uniform\r
     *    series of grey shades running between black and white (but\r
     *    not including either, since actual black and white are\r
     *    already provided in the previous colour cube).\r
     *\r
     * After that, we have the remaining 6 special colours:\r
     */                                         \\r
    X(fg)                                       \\r
    X(fg_bold)                                  \\r
    X(bg)                                       \\r
    X(bg_bold)                                  \\r
    X(cursor_fg)                                \\r
    X(cursor_bg)                                \\r
    /* end of list */\r
\r
/* Enumerations of the colour lists. These are available everywhere in\r
 * the code. The OSC P encoding shouldn't be used outside terminal.c,\r
 * but the easiest way to define the OSC 4 enum is to have the OSC P\r
 * one available to compute with. */\r
enum {\r
    #define ENUM_DECL(id,name) CONF_COLOUR_##id,\r
    CONF_COLOUR_LIST(ENUM_DECL)\r
    #undef ENUM_DECL\r
};\r
enum {\r
    #define ENUM_DECL(id) OSCP_COLOUR_##id,\r
    OSCP_COLOUR_LIST(ENUM_DECL)\r
    #undef ENUM_DECL\r
};\r
enum {\r
    #define ENUM_DECL(id) OSC4_COLOUR_##id = \\r
        OSCP_COLOUR_##id + (OSCP_COLOUR_##id >= 16 ? 240 : 0),\r
    OSCP_COLOUR_LIST(ENUM_DECL)\r
    #undef ENUM_DECL\r
};\r
\r
/* Mapping tables defined in terminal.c */\r
extern const int colour_indices_conf_to_oscp[CONF_NCOLOURS];\r
extern const int colour_indices_conf_to_osc4[CONF_NCOLOURS];\r
extern const int colour_indices_oscp_to_osc4[OSCP_NCOLOURS];\r
\r
/* Three attribute types:\r
 * The ATTRs (normal attributes) are stored with the characters in\r
 * the main display arrays\r
 *\r
 * The TATTRs (temporary attributes) are generated on the fly, they\r
 * can overlap with characters but not with normal attributes.\r
 *\r
 * The LATTRs (line attributes) are an entirely disjoint space of\r
 * flags.\r
 *\r
 * The DATTRs (display attributes) are internal to terminal.c (but\r
 * defined here because their values have to match the others\r
 * here); they reuse the TATTR_* space but are always masked off\r
 * before sending to the front end.\r
 *\r
 * ATTR_INVALID is an illegal colour combination.\r
 */\r
\r
#define TATTR_ACTCURS       0x40000000UL      /* active cursor (block) */\r
#define TATTR_PASCURS       0x20000000UL      /* passive cursor (box) */\r
#define TATTR_RIGHTCURS     0x10000000UL      /* cursor-on-RHS */\r
#define TATTR_COMBINING     0x80000000UL      /* combining characters */\r
\r
#define DATTR_STARTRUN      0x80000000UL   /* start of redraw run */\r
\r
#define TDATTR_MASK         0xF0000000UL\r
#define TATTR_MASK (TDATTR_MASK)\r
#define DATTR_MASK (TDATTR_MASK)\r
\r
#define LATTR_NORM   0x00000000UL\r
#define LATTR_WIDE   0x00000001UL\r
#define LATTR_TOP    0x00000002UL\r
#define LATTR_BOT    0x00000003UL\r
#define LATTR_MODE   0x00000003UL\r
#define LATTR_WRAPPED 0x00000010UL     /* this line wraps to next */\r
#define LATTR_WRAPPED2 0x00000020UL    /* with WRAPPED: CJK wide character\r
                                          wrapped to next line, so last\r
                                          single-width cell is empty */\r
\r
#define ATTR_INVALID 0x03FFFFU\r
\r
/* Use the DC00 page for direct to font. */\r
#define CSET_OEMCP   0x0000DC00UL      /* OEM Codepage DTF */\r
#define CSET_ACP     0x0000DD00UL      /* Ansi Codepage DTF */\r
\r
/* These are internal use overlapping with the UTF-16 surrogates */\r
#define CSET_ASCII   0x0000D800UL      /* normal ASCII charset ESC ( B */\r
#define CSET_LINEDRW 0x0000D900UL      /* line drawing charset ESC ( 0 */\r
#define CSET_SCOACS  0x0000DA00UL      /* SCO Alternate charset */\r
#define CSET_GBCHR   0x0000DB00UL      /* UK variant   charset ESC ( A */\r
#define CSET_MASK    0xFFFFFF00UL      /* Character set mask */\r
\r
#define DIRECT_CHAR(c) ((c&0xFFFFFC00)==0xD800)\r
#define DIRECT_FONT(c) ((c&0xFFFFFE00)==0xDC00)\r
\r
#define UCSERR       (CSET_LINEDRW|'a') /* UCS Format error character. */\r
/*\r
 * UCSWIDE is a special value used in the terminal data to signify\r
 * the character cell containing the right-hand half of a CJK wide\r
 * character. We use 0xDFFF because it's part of the surrogate\r
 * range and hence won't be used for anything else (it's impossible\r
 * to input it via UTF-8 because our UTF-8 decoder correctly\r
 * rejects surrogates).\r
 */\r
#define UCSWIDE      0xDFFF\r
\r
#define ATTR_NARROW  0x0800000U\r
#define ATTR_WIDE    0x0400000U\r
#define ATTR_BOLD    0x0040000U\r
#define ATTR_UNDER   0x0080000U\r
#define ATTR_REVERSE 0x0100000U\r
#define ATTR_BLINK   0x0200000U\r
#define ATTR_FGMASK  0x00001FFU /* stores a colour in OSC 4 indexing */\r
#define ATTR_BGMASK  0x003FE00U /* stores a colour in OSC 4 indexing */\r
#define ATTR_COLOURS 0x003FFFFU\r
#define ATTR_DIM     0x1000000U\r
#define ATTR_STRIKE  0x2000000U\r
#define ATTR_FGSHIFT 0\r
#define ATTR_BGSHIFT 9\r
\r
#define ATTR_DEFFG   (OSC4_COLOUR_fg << ATTR_FGSHIFT)\r
#define ATTR_DEFBG   (OSC4_COLOUR_bg << ATTR_BGSHIFT)\r
#define ATTR_DEFAULT (ATTR_DEFFG | ATTR_DEFBG)\r
\r
struct sesslist {\r
    int nsessions;\r
    const char **sessions;\r
    char *buffer;                      /* so memory can be freed later */\r
};\r
\r
struct unicode_data {\r
    bool dbcs_screenfont;\r
    int font_codepage;\r
    int line_codepage;\r
    wchar_t unitab_scoacs[256];\r
    wchar_t unitab_line[256];\r
    wchar_t unitab_font[256];\r
    wchar_t unitab_xterm[256];\r
    wchar_t unitab_oemcp[256];\r
    unsigned char unitab_ctrl[256];\r
};\r
\r
#define LGXF_OVR  1                    /* existing logfile overwrite */\r
#define LGXF_APN  0                    /* existing logfile append */\r
#define LGXF_ASK -1                    /* existing logfile ask */\r
#define LGTYP_NONE  0                  /* logmode: no logging */\r
#define LGTYP_ASCII 1                  /* logmode: pure ascii */\r
#define LGTYP_DEBUG 2                  /* logmode: all chars of traffic */\r
#define LGTYP_PACKETS 3                /* logmode: SSH data packets */\r
#define LGTYP_SSHRAW 4                 /* logmode: SSH raw data */\r
\r
/*\r
 * Enumeration of 'special commands' that can be sent during a\r
 * session, separately from the byte stream of ordinary session data.\r
 */\r
typedef enum {\r
    /*\r
     * Commands that are generally useful in multiple backends.\r
     */\r
    SS_BRK,    /* serial-line break */\r
    SS_EOF,    /* end-of-file on session input */\r
    SS_NOP,    /* transmit data with no effect */\r
    SS_PING,   /* try to keep the session alive (probably, but not\r
                * necessarily, implemented as SS_NOP) */\r
\r
    /*\r
     * Commands specific to Telnet.\r
     */\r
    SS_AYT,    /* Are You There */\r
    SS_SYNCH,  /* Synch */\r
    SS_EC,     /* Erase Character */\r
    SS_EL,     /* Erase Line */\r
    SS_GA,     /* Go Ahead */\r
    SS_ABORT,  /* Abort Process */\r
    SS_AO,     /* Abort Output */\r
    SS_IP,     /* Interrupt Process */\r
    SS_SUSP,   /* Suspend Process */\r
    SS_EOR,    /* End Of Record */\r
    SS_EOL,    /* Telnet end-of-line sequence (CRLF, as opposed to CR\r
                * NUL that escapes a literal CR) */\r
\r
    /*\r
     * Commands specific to SSH.\r
     */\r
    SS_REKEY,  /* trigger an immediate repeat key exchange */\r
    SS_XCERT,  /* cross-certify another host key ('arg' indicates which) */\r
\r
    /*\r
     * Send a POSIX-style signal. (Useful in SSH and also pterm.)\r
     *\r
     * We use the master list in ssh/signal-list.h to define these enum\r
     * values, which will come out looking like names of the form\r
     * SS_SIGABRT, SS_SIGINT etc.\r
     */\r
    #define SIGNAL_MAIN(name, text) SS_SIG ## name,\r
    #define SIGNAL_SUB(name) SS_SIG ## name,\r
    #include "ssh/signal-list.h"\r
    #undef SIGNAL_MAIN\r
    #undef SIGNAL_SUB\r
\r
    /*\r
     * These aren't really special commands, but they appear in the\r
     * enumeration because the list returned from\r
     * backend_get_specials() will use them to specify the structure\r
     * of the GUI specials menu.\r
     */\r
    SS_SEP,         /* Separator */\r
    SS_SUBMENU,     /* Start a new submenu with specified name */\r
    SS_EXITMENU,    /* Exit current submenu, or end of entire specials list */\r
} SessionSpecialCode;\r
\r
/*\r
 * The structure type returned from backend_get_specials.\r
 */\r
struct SessionSpecial {\r
    const char *name;\r
    SessionSpecialCode code;\r
    int arg;\r
};\r
\r
/* Needed by both ssh/channel.h and ssh/ppl.h */\r
typedef void (*add_special_fn_t)(\r
    void *ctx, const char *text, SessionSpecialCode code, int arg);\r
\r
typedef enum {\r
    MBT_NOTHING,\r
    MBT_LEFT, MBT_MIDDLE, MBT_RIGHT,   /* `raw' button designations */\r
    MBT_SELECT, MBT_EXTEND, MBT_PASTE, /* `cooked' button designations */\r
    MBT_WHEEL_UP, MBT_WHEEL_DOWN,      /* vertical mouse wheel */\r
    MBT_WHEEL_LEFT, MBT_WHEEL_RIGHT    /* horizontal mouse wheel */\r
} Mouse_Button;\r
\r
typedef enum {\r
    MA_NOTHING, MA_CLICK, MA_2CLK, MA_3CLK, MA_DRAG, MA_RELEASE, MA_MOVE\r
} Mouse_Action;\r
\r
/* Keyboard modifiers -- keys the user is actually holding down */\r
\r
#define PKM_SHIFT       0x01\r
#define PKM_CONTROL     0x02\r
#define PKM_META        0x04\r
#define PKM_ALT         0x08\r
\r
/* Keyboard flags that aren't really modifiers */\r
#define PKF_CAPSLOCK    0x10\r
#define PKF_NUMLOCK     0x20\r
#define PKF_REPEAT      0x40\r
\r
/* Stand-alone keysyms for function keys */\r
\r
typedef enum {\r
    PK_NULL,            /* No symbol for this key */\r
    /* Main keypad keys */\r
    PK_ESCAPE, PK_TAB, PK_BACKSPACE, PK_RETURN, PK_COMPOSE,\r
    /* Editing keys */\r
    PK_HOME, PK_INSERT, PK_DELETE, PK_END, PK_PAGEUP, PK_PAGEDOWN,\r
    /* Cursor keys */\r
    PK_UP, PK_DOWN, PK_RIGHT, PK_LEFT, PK_REST,\r
    /* Numeric keypad */                        /* Real one looks like: */\r
    PK_PF1, PK_PF2, PK_PF3, PK_PF4,             /* PF1 PF2 PF3 PF4 */\r
    PK_KPCOMMA, PK_KPMINUS, PK_KPDECIMAL,       /*  7   8   9   -  */\r
    PK_KP0, PK_KP1, PK_KP2, PK_KP3, PK_KP4,     /*  4   5   6   ,  */\r
    PK_KP5, PK_KP6, PK_KP7, PK_KP8, PK_KP9,     /*  1   2   3  en- */\r
    PK_KPBIGPLUS, PK_KPENTER,                   /*    0     .  ter */\r
    /* Top row */\r
    PK_F1,  PK_F2,  PK_F3,  PK_F4,  PK_F5,\r
    PK_F6,  PK_F7,  PK_F8,  PK_F9,  PK_F10,\r
    PK_F11, PK_F12, PK_F13, PK_F14, PK_F15,\r
    PK_F16, PK_F17, PK_F18, PK_F19, PK_F20,\r
    PK_PAUSE\r
} Key_Sym;\r
\r
#define PK_ISEDITING(k) ((k) >= PK_HOME && (k) <= PK_PAGEDOWN)\r
#define PK_ISCURSOR(k)  ((k) >= PK_UP && (k) <= PK_REST)\r
#define PK_ISKEYPAD(k)  ((k) >= PK_PF1 && (k) <= PK_KPENTER)\r
#define PK_ISFKEY(k)    ((k) >= PK_F1 && (k) <= PK_F20)\r
\r
enum {\r
    VT_XWINDOWS, VT_OEMANSI, VT_OEMONLY, VT_POORMAN, VT_UNICODE\r
};\r
\r
enum {\r
    /*\r
     * SSH-2 key exchange algorithms\r
     */\r
    KEX_WARN,\r
    KEX_DHGROUP1,\r
    KEX_DHGROUP14,\r
    KEX_DHGROUP15,\r
    KEX_DHGROUP16,\r
    KEX_DHGROUP17,\r
    KEX_DHGROUP18,\r
    KEX_DHGEX,\r
    KEX_RSA,\r
    KEX_ECDH,\r
    KEX_NTRU_HYBRID,\r
    KEX_MAX\r
};\r
\r
enum {\r
    /*\r
     * SSH-2 host key algorithms\r
     */\r
    HK_WARN,\r
    HK_RSA,\r
    HK_DSA,\r
    HK_ECDSA,\r
    HK_ED25519,\r
    HK_ED448,\r
    HK_MAX\r
};\r
\r
enum {\r
    /*\r
     * SSH ciphers (both SSH-1 and SSH-2)\r
     */\r
    CIPHER_WARN,                       /* pseudo 'cipher' */\r
    CIPHER_3DES,\r
    CIPHER_BLOWFISH,\r
    CIPHER_AES,                        /* (SSH-2 only) */\r
    CIPHER_DES,\r
    CIPHER_ARCFOUR,\r
    CIPHER_CHACHA20,\r
    CIPHER_AESGCM,\r
    CIPHER_MAX                         /* no. ciphers (inc warn) */\r
};\r
\r
enum TriState {\r
    /*\r
     * Several different bits of the PuTTY configuration seem to be\r
     * three-way settings whose values are `always yes', `always\r
     * no', and `decide by some more complex automated means'. This\r
     * is true of line discipline options (local echo and line\r
     * editing), proxy DNS, proxy terminal logging, Close On Exit, and\r
     * SSH server bug workarounds. Accordingly I supply a single enum\r
     * here to deal with them all.\r
     */\r
    FORCE_ON, FORCE_OFF, AUTO\r
};\r
\r
enum {\r
    /*\r
     * Proxy types.\r
     */\r
    PROXY_NONE, PROXY_SOCKS4, PROXY_SOCKS5,\r
    PROXY_HTTP, PROXY_TELNET, PROXY_CMD, PROXY_SSH_TCPIP,\r
    PROXY_SSH_EXEC, PROXY_SSH_SUBSYSTEM,\r
    PROXY_FUZZ\r
};\r
\r
enum {\r
    /*\r
     * Line discipline options which the backend might try to control.\r
     */\r
    LD_EDIT,                           /* local line editing */\r
    LD_ECHO,                           /* local echo */\r
    LD_N_OPTIONS\r
};\r
\r
enum {\r
    /* Actions on remote window title query */\r
    TITLE_NONE, TITLE_EMPTY, TITLE_REAL\r
};\r
\r
enum {\r
    /* SUPDUP character set options */\r
    SUPDUP_CHARSET_ASCII, SUPDUP_CHARSET_ITS, SUPDUP_CHARSET_WAITS\r
};\r
\r
enum {\r
    /* Protocol back ends. (CONF_protocol) */\r
    PROT_RAW, PROT_TELNET, PROT_RLOGIN, PROT_SSH, PROT_SSHCONN,\r
    /* PROT_SERIAL is supported on a subset of platforms, but it doesn't\r
     * hurt to define it globally. */\r
    PROT_SERIAL,\r
    /* PROT_SUPDUP is the historical RFC 734 protocol. */\r
    PROT_SUPDUP,\r
    PROTOCOL_LIMIT, /* upper bound on number of protocols */\r
};\r
\r
enum {\r
    /* Bell settings (CONF_beep) */\r
    BELL_DISABLED, BELL_DEFAULT, BELL_VISUAL, BELL_WAVEFILE, BELL_PCSPEAKER\r
};\r
\r
enum {\r
    /* Taskbar flashing indication on bell (CONF_beep_ind) */\r
    B_IND_DISABLED, B_IND_FLASH, B_IND_STEADY\r
};\r
\r
enum {\r
    /* Resize actions (CONF_resize_action) */\r
    RESIZE_TERM, RESIZE_DISABLED, RESIZE_FONT, RESIZE_EITHER\r
};\r
\r
enum {\r
    /* Function key types (CONF_funky_type) */\r
    FUNKY_TILDE,\r
    FUNKY_LINUX,\r
    FUNKY_XTERM,\r
    FUNKY_VT400,\r
    FUNKY_VT100P,\r
    FUNKY_SCO,\r
    FUNKY_XTERM_216\r
};\r
\r
enum {\r
    /* Shifted arrow key types (CONF_sharrow_type) */\r
    SHARROW_APPLICATION,  /* Ctrl flips between ESC O A and ESC [ A */\r
    SHARROW_BITMAP        /* ESC [ 1 ; n A, where n = 1 + bitmap of CAS */\r
};\r
\r
enum {\r
    FQ_DEFAULT, FQ_ANTIALIASED, FQ_NONANTIALIASED, FQ_CLEARTYPE\r
};\r
\r
enum {\r
    SER_PAR_NONE, SER_PAR_ODD, SER_PAR_EVEN, SER_PAR_MARK, SER_PAR_SPACE\r
};\r
\r
enum {\r
    SER_FLOW_NONE, SER_FLOW_XONXOFF, SER_FLOW_RTSCTS, SER_FLOW_DSRDTR\r
};\r
\r
/*\r
 * Tables of string <-> enum value mappings used in settings.c.\r
 * Defined here so that backends can export their GSS library tables\r
 * to the cross-platform settings code.\r
 */\r
struct keyvalwhere {\r
    /*\r
     * Two fields which define a string and enum value to be\r
     * equivalent to each other.\r
     */\r
    const char *s;\r
    int v;\r
\r
    /*\r
     * The next pair of fields are used by gprefs() in settings.c to\r
     * arrange that when it reads a list of strings representing a\r
     * preference list and translates it into the corresponding list\r
     * of integers, strings not appearing in the list are entered in a\r
     * configurable position rather than uniformly at the end.\r
     */\r
\r
    /*\r
     * 'vrel' indicates which other value in the list to place this\r
     * element relative to. It should be a value that has occurred in\r
     * a 'v' field of some other element of the array, or -1 to\r
     * indicate that we simply place relative to one or other end of\r
     * the list.\r
     *\r
     * gprefs will try to process the elements in an order which makes\r
     * this field work (i.e. so that the element referenced has been\r
     * added before processing this one).\r
     */\r
    int vrel;\r
\r
    /*\r
     * 'where' indicates whether to place the new value before or\r
     * after the one referred to by vrel. -1 means before; +1 means\r
     * after.\r
     *\r
     * When vrel is -1, this also implicitly indicates which end of\r
     * the array to use. So vrel=-1, where=-1 means to place _before_\r
     * some end of the list (hence, at the last element); vrel=-1,\r
     * where=+1 means to place _after_ an end (hence, at the first).\r
     */\r
    int where;\r
};\r
\r
#ifndef NO_GSSAPI\r
extern const int ngsslibs;\r
extern const char *const gsslibnames[]; /* for displaying in configuration */\r
extern const struct keyvalwhere gsslibkeywords[]; /* for settings.c */\r
#endif\r
\r
extern const char *const ttymodes[];\r
\r
enum {\r
    /*\r
     * Network address types. Used for specifying choice of IPv4/v6\r
     * in config; also used in proxy.c to indicate whether a given\r
     * host name has already been resolved or will be resolved at\r
     * the proxy end.\r
     */\r
    ADDRTYPE_UNSPEC,\r
    ADDRTYPE_IPV4,\r
    ADDRTYPE_IPV6,\r
    ADDRTYPE_LOCAL,    /* e.g. Unix domain socket, or Windows named pipe */\r
    ADDRTYPE_NAME      /* SockAddr storing an unresolved host name */\r
};\r
\r
/* Backend flags */\r
#define BACKEND_RESIZE_FORBIDDEN    0x01   /* Backend does not allow\r
                                              resizing terminal */\r
#define BACKEND_NEEDS_TERMINAL      0x02   /* Backend must have terminal */\r
#define BACKEND_SUPPORTS_NC_HOST    0x04   /* Backend can honour\r
                                              CONF_ssh_nc_host */\r
#define BACKEND_NOTIFIES_SESSION_START 0x08 /* Backend will call\r
                                               seat_notify_session_started */\r
\r
/* In (no)sshproxy.c */\r
extern const bool ssh_proxy_supported;\r
\r
/*\r
 * This structure type wraps a Seat pointer, in a way that has no\r
 * purpose except to be a different type.\r
 *\r
 * The Seat wrapper functions that present interactive prompts all\r
 * expect one of these in place of their ordinary Seat pointer. You\r
 * get one by calling interactor_announce (defined below), which will\r
 * print a message (if not already done) identifying the Interactor\r
 * that originated the prompt.\r
 *\r
 * This arranges that the C type system itself will check that no call\r
 * to any of those Seat methods has omitted the mandatory call to\r
 * interactor_announce beforehand.\r
 */\r
struct InteractionReadySeat {\r
    Seat *seat;\r
};\r
\r
/*\r
 * The Interactor trait is implemented by anything that is capable of\r
 * presenting interactive prompts or questions to the user during\r
 * network connection setup. Every Backend that ever needs to do this\r
 * is an Interactor, but also, while a Backend is making its initial\r
 * network connection, it may go via network proxy code which is also\r
 * an Interactor and can ask questions of its own.\r
 */\r
struct Interactor {\r
    const InteractorVtable *vt;\r
\r
    /* The parent Interactor that we are a proxy for, if any. */\r
    Interactor *parent;\r
\r
    /*\r
     * If we're the top-level Interactor (parent==NULL), then this\r
     * field records the last Interactor that actually did anything\r
     * interactive, so that we know when to announce a changeover\r
     * between levels of proxying.\r
     *\r
     * If parent != NULL, this field is not used.\r
     */\r
    Interactor *last_to_talk;\r
};\r
\r
struct InteractorVtable {\r
    /*\r
     * Returns a user-facing description of the nature of the network\r
     * connection being made. Used in interactive proxy authentication\r
     * to announce which connection attempt is now in control of the\r
     * Seat.\r
     *\r
     * The idea is not just to be written in natural language, but to\r
     * connect with the user's idea of _why_ they think some\r
     * connection is being made. For example, instead of saying 'TCP\r
     * connection to 123.45.67.89 port 22', you might say 'SSH\r
     * connection to [logical host name for SSH host key purposes]'.\r
     *\r
     * The returned string must be freed by the caller.\r
     */\r
    char *(*description)(Interactor *itr);\r
\r
    /*\r
     * Returns the LogPolicy associated with this Interactor. (A\r
     * Backend can derive this from its logging context; a proxy\r
     * Interactor inherits it from the Interactor for the parent\r
     * network connection.)\r
     */\r
    LogPolicy *(*logpolicy)(Interactor *itr);\r
\r
    /*\r
     * Gets and sets the Seat that this Interactor talks to. When a\r
     * Seat is borrowed and replaced with a TempSeat, this will be the\r
     * mechanism by which that replacement happens.\r
     */\r
    Seat *(*get_seat)(Interactor *itr);\r
    void (*set_seat)(Interactor *itr, Seat *seat);\r
};\r
\r
static inline char *interactor_description(Interactor *itr)\r
{ return itr->vt->description(itr); }\r
static inline LogPolicy *interactor_logpolicy(Interactor *itr)\r
{ return itr->vt->logpolicy(itr); }\r
static inline Seat *interactor_get_seat(Interactor *itr)\r
{ return itr->vt->get_seat(itr); }\r
static inline void interactor_set_seat(Interactor *itr, Seat *seat)\r
{ itr->vt->set_seat(itr, seat); }\r
\r
static inline void interactor_set_child(Interactor *parent, Interactor *child)\r
{ child->parent = parent; }\r
Seat *interactor_borrow_seat(Interactor *itr);\r
void interactor_return_seat(Interactor *itr);\r
InteractionReadySeat interactor_announce(Interactor *itr);\r
\r
/* Interactors that are Backends will find this helper function useful\r
 * in constructing their description strings */\r
char *default_description(const BackendVtable *backvt,\r
                          const char *host, int port);\r
\r
/*\r
 * The Backend trait is the top-level one that governs each of the\r
 * user-facing main modes that PuTTY can use to talk to some\r
 * destination: SSH, Telnet, serial port, pty, etc.\r
 */\r
\r
struct Backend {\r
    const BackendVtable *vt;\r
\r
    /* Many Backends are also Interactors. If this one is, a pointer\r
     * to its Interactor trait lives here. */\r
    Interactor *interactor;\r
};\r
struct BackendVtable {\r
    char *(*init) (const BackendVtable *vt, Seat *seat,\r
                   Backend **backend_out, LogContext *logctx, Conf *conf,\r
                   const char *host, int port, char **realhost,\r
                   bool nodelay, bool keepalive);\r
\r
    void (*free) (Backend *be);\r
    /* Pass in a replacement configuration. */\r
    void (*reconfig) (Backend *be, Conf *conf);\r
    void (*send) (Backend *be, const char *buf, size_t len);\r
    /* sendbuffer() returns the current amount of buffered data */\r
    size_t (*sendbuffer) (Backend *be);\r
    void (*size) (Backend *be, int width, int height);\r
    void (*special) (Backend *be, SessionSpecialCode code, int arg);\r
    const SessionSpecial *(*get_specials) (Backend *be);\r
    bool (*connected) (Backend *be);\r
    int (*exitcode) (Backend *be);\r
    /* If back->sendok() returns false, the backend doesn't currently\r
     * want input data, so the frontend should avoid acquiring any if\r
     * possible (passing back-pressure on to its sender).\r
     *\r
     * Policy rule: no backend shall return true from sendok() while\r
     * its network connection attempt is still ongoing. This ensures\r
     * that if making the network connection involves a proxy type\r
     * which wants to interact with the user via the terminal, the\r
     * proxy implementation and the backend itself won't fight over\r
     * who gets the terminal input. */\r
    bool (*sendok) (Backend *be);\r
    bool (*ldisc_option_state) (Backend *be, int);\r
    void (*provide_ldisc) (Backend *be, Ldisc *ldisc);\r
    /* Tells the back end that the front end  buffer is clearing. */\r
    void (*unthrottle) (Backend *be, size_t bufsize);\r
    int (*cfg_info) (Backend *be);\r
\r
    /* Only implemented in the SSH protocol: check whether a\r
     * connection-sharing upstream exists for a given configuration. */\r
    bool (*test_for_upstream)(const char *host, int port, Conf *conf);\r
    /* Special-purpose function to return additional information to put\r
     * in a "are you sure you want to close this session" dialog;\r
     * return NULL if no such info, otherwise caller must free.\r
     * Only implemented in the SSH protocol, to warn about downstream\r
     * connections that would be lost if this one were terminated. */\r
    char *(*close_warn_text)(Backend *be);\r
\r
    /* 'id' is a machine-readable name for the backend, used in\r
     * saved-session storage. 'displayname_tc' and 'displayname_lc'\r
     * are human-readable names, one in title-case for config boxes,\r
     * and one in lower-case for use in mid-sentence. */\r
    const char *id, *displayname_tc, *displayname_lc;\r
\r
    int protocol;\r
    int default_port;\r
    unsigned flags;\r
\r
    /* Only relevant for the serial protocol: bit masks of which\r
     * parity and flow control settings are supported. */\r
    unsigned serial_parity_mask, serial_flow_mask;\r
};\r
\r
static inline char *backend_init(\r
    const BackendVtable *vt, Seat *seat, Backend **out, LogContext *logctx,\r
    Conf *conf, const char *host, int port, char **rhost, bool nd, bool ka)\r
{ return vt->init(vt, seat, out, logctx, conf, host, port, rhost, nd, ka); }\r
static inline void backend_free(Backend *be)\r
{ be->vt->free(be); }\r
static inline void backend_reconfig(Backend *be, Conf *conf)\r
{ be->vt->reconfig(be, conf); }\r
static inline void backend_send(Backend *be, const char *buf, size_t len)\r
{ be->vt->send(be, buf, len); }\r
static inline size_t backend_sendbuffer(Backend *be)\r
{ return be->vt->sendbuffer(be); }\r
static inline void backend_size(Backend *be, int width, int height)\r
{ be->vt->size(be, width, height); }\r
static inline void backend_special(\r
    Backend *be, SessionSpecialCode code, int arg)\r
{ be->vt->special(be, code, arg); }\r
static inline const SessionSpecial *backend_get_specials(Backend *be)\r
{ return be->vt->get_specials(be); }\r
static inline bool backend_connected(Backend *be)\r
{ return be->vt->connected(be); }\r
static inline int backend_exitcode(Backend *be)\r
{ return be->vt->exitcode(be); }\r
static inline bool backend_sendok(Backend *be)\r
{ return be->vt->sendok(be); }\r
static inline bool backend_ldisc_option_state(Backend *be, int state)\r
{ return be->vt->ldisc_option_state(be, state); }\r
static inline void backend_provide_ldisc(Backend *be, Ldisc *ldisc)\r
{ be->vt->provide_ldisc(be, ldisc); }\r
static inline void backend_unthrottle(Backend *be, size_t bufsize)\r
{ be->vt->unthrottle(be, bufsize); }\r
static inline int backend_cfg_info(Backend *be)\r
{ return be->vt->cfg_info(be); }\r
\r
extern const struct BackendVtable *const backends[];\r
/*\r
 * In programs with a config UI, only the first few members of\r
 * backends[] will be displayed at the top-level; the others will be\r
 * relegated to a drop-down.\r
 */\r
extern const size_t n_ui_backends;\r
\r
/*\r
 * Suggested default protocol provided by the backend link module.\r
 * The application is free to ignore this.\r
 */\r
extern const int be_default_protocol;\r
\r
/*\r
 * Name of this particular application, for use in the config box\r
 * and other pieces of text.\r
 */\r
extern const char *const appname;\r
\r
/*\r
 * Used by callback.c; declared up here so that prompts_t can use it\r
 */\r
typedef void (*toplevel_callback_fn_t)(void *ctx);\r
\r
/* Enum of result types in SeatPromptResult below */\r
typedef enum SeatPromptResultKind {\r
    /* Answer not yet available at all; either try again later or wait\r
     * for a callback (depending on the request's API) */\r
    SPRK_INCOMPLETE,\r
\r
    /* We're abandoning the connection because the user interactively\r
     * told us to. (Hence, no need to present an error message\r
     * telling the user we're doing that: they already know.) */\r
    SPRK_USER_ABORT,\r
\r
    /* We're abandoning the connection for some other reason (e.g. we\r
     * were unable to present the prompt at all, or a batch-mode\r
     * configuration told us to give the answer no). This may\r
     * ultimately have stemmed from some user configuration, but they\r
     * didn't _tell us right now_ to abandon this connection, so we\r
     * still need to inform them that we've done so. */\r
    SPRK_SW_ABORT,\r
\r
    /* We're proceeding with the connection and have all requested\r
     * information (if any) */\r
    SPRK_OK\r
} SeatPromptResultKind;\r
\r
/* Small struct to present the results of interactive requests from\r
 * backend to Seat (see below) */\r
struct SeatPromptResult {\r
    SeatPromptResultKind kind;\r
\r
    /*\r
     * In the case of SPRK_SW_ABORT, the frontend provides an error\r
     * message to present to the user. But dynamically allocating it\r
     * up front would mean having to make sure it got freed at any\r
     * call site where one of these structs is received (and freed\r
     * _once_ no matter how many times the struct is copied). So\r
     * instead we provide a function that will generate the error\r
     * message into a BinarySink.\r
     */\r
    void (*errfn)(SeatPromptResult, BinarySink *);\r
\r
    /*\r
     * And some fields the error function can use to construct the\r
     * message (holding, e.g. an OS error code).\r
     */\r
    const char *errdata_lit; /* statically allocated, e.g. a string literal */\r
    unsigned errdata_u;\r
};\r
\r
/* Helper function to construct the simple versions of these\r
 * structures inline */\r
static inline SeatPromptResult make_spr_simple(SeatPromptResultKind kind)\r
{\r
    SeatPromptResult spr;\r
    spr.kind = kind;\r
    spr.errdata_lit = NULL;\r
    return spr;\r
}\r
\r
/* Most common constructor function for SPRK_SW_ABORT errors */\r
SeatPromptResult make_spr_sw_abort_static(const char *);\r
\r
/* Convenience macros wrapping those constructors in turn */\r
#define SPR_INCOMPLETE make_spr_simple(SPRK_INCOMPLETE)\r
#define SPR_USER_ABORT make_spr_simple(SPRK_USER_ABORT)\r
#define SPR_SW_ABORT(lit) make_spr_sw_abort_static(lit)\r
#define SPR_OK make_spr_simple(SPRK_OK)\r
\r
/* Query function that folds both kinds of abort together */\r
static inline bool spr_is_abort(SeatPromptResult spr)\r
{\r
    return spr.kind == SPRK_USER_ABORT || spr.kind == SPRK_SW_ABORT;\r
}\r
\r
/* Function to return a dynamically allocated copy of the error message */\r
char *spr_get_error_message(SeatPromptResult spr);\r
\r
/*\r
 * Mechanism for getting text strings such as usernames and passwords\r
 * from the front-end.\r
 * The fields are mostly modelled after SSH's keyboard-interactive auth.\r
 * FIXME We should probably mandate a character set/encoding (probably UTF-8).\r
 *\r
 * Since many of the pieces of text involved may be chosen by the server,\r
 * the caller must take care to ensure that the server can't spoof locally-\r
 * generated prompts such as key passphrase prompts. Some ground rules:\r
 *  - If the front-end needs to truncate a string, it should lop off the\r
 *    end.\r
 *  - The front-end should filter out any dangerous characters and\r
 *    generally not trust the strings. (But \n is required to behave\r
 *    vaguely sensibly, at least in `instruction', and ideally in\r
 *    `prompt[]' too.)\r
 */\r
typedef struct {\r
    char *prompt;\r
    bool echo;\r
    strbuf *result;\r
} prompt_t;\r
typedef struct prompts_t prompts_t;\r
struct prompts_t {\r
    /*\r
     * Indicates whether the information entered is to be used locally\r
     * (for instance a key passphrase prompt), or is destined for the wire.\r
     * This is a hint only; the front-end is at liberty not to use this\r
     * information (so the caller should ensure that the supplied text is\r
     * sufficient).\r
     */\r
    bool to_server;\r
\r
    /*\r
     * Indicates whether the prompts originated _at_ the server, so\r
     * that the front end can display some kind of trust sigil that\r
     * distinguishes (say) a legit private-key passphrase prompt from\r
     * a fake one sent by a malicious server.\r
     */\r
    bool from_server;\r
\r
    char *name;         /* Short description, perhaps for dialog box title */\r
    bool name_reqd;     /* Display of `name' required or optional? */\r
    char *instruction;  /* Long description, maybe with embedded newlines */\r
    bool instr_reqd;    /* Display of `instruction' required or optional? */\r
    size_t n_prompts;   /* May be zero (in which case display the foregoing,\r
                         * if any, and return success) */\r
    size_t prompts_size; /* allocated storage capacity for prompts[] */\r
    prompt_t **prompts;\r
    void *data;         /* slot for housekeeping data, managed by\r
                         * seat_get_userpass_input(); initially NULL */\r
    SeatPromptResult spr; /* some implementations need to cache one of these */\r
\r
    /*\r
     * Callback you can fill in to be notified when all the prompts'\r
     * responses are available. After you receive this notification, a\r
     * further call to the get_userpass_input function will return the\r
     * final state of the prompts system, which is guaranteed not to\r
     * be negative for 'still ongoing'.\r
     */\r
    toplevel_callback_fn_t callback;\r
    void *callback_ctx;\r
\r
    /*\r
     * When this prompts_t is known to an Ldisc, we might need to\r
     * break the connection if things get freed in an emergency. So\r
     * this is a pointer to the Ldisc's pointer to us.\r
     */\r
    prompts_t **ldisc_ptr_to_us;\r
};\r
prompts_t *new_prompts(void);\r
void add_prompt(prompts_t *p, char *promptstr, bool echo);\r
void prompt_set_result(prompt_t *pr, const char *newstr);\r
char *prompt_get_result(prompt_t *pr);\r
const char *prompt_get_result_ref(prompt_t *pr);\r
void free_prompts(prompts_t *p);\r
\r
/*\r
 * Data type definitions for true-colour terminal display.\r
 * 'optionalrgb' describes a single RGB colour, which overrides the\r
 * other colour settings if 'enabled' is nonzero, and is ignored\r
 * otherwise. 'truecolour' contains a pair of those for foreground and\r
 * background.\r
 */\r
typedef struct optionalrgb {\r
    bool enabled;\r
    unsigned char r, g, b;\r
} optionalrgb;\r
extern const optionalrgb optionalrgb_none;\r
typedef struct truecolour {\r
    optionalrgb fg, bg;\r
} truecolour;\r
#define optionalrgb_equal(r1,r2) (                              \\r
        (r1).enabled==(r2).enabled &&                           \\r
        (r1).r==(r2).r && (r1).g==(r2).g && (r1).b==(r2).b)\r
#define truecolour_equal(c1,c2) (               \\r
        optionalrgb_equal((c1).fg, (c2).fg) &&  \\r
        optionalrgb_equal((c1).bg, (c2).bg))\r
\r
/*\r
 * Enumeration of clipboards. We provide some standard ones cross-\r
 * platform, and then permit each platform to extend this enumeration\r
 * further by defining PLATFORM_CLIPBOARDS in its own header file.\r
 *\r
 * CLIP_NULL is a non-clipboard, writes to which are ignored and reads\r
 * from which return no data.\r
 *\r
 * CLIP_LOCAL refers to a buffer within terminal.c, which\r
 * unconditionally saves the last data selected in the terminal. In\r
 * configurations where a system clipboard is not written\r
 * automatically on selection but instead by an explicit UI action,\r
 * this is where the code responding to that action can find the data\r
 * to write to the clipboard in question.\r
 */\r
#define CROSS_PLATFORM_CLIPBOARDS(X)                    \\r
    X(CLIP_NULL, "null clipboard")                      \\r
    X(CLIP_LOCAL, "last text selected in terminal")     \\r
    /* end of list */\r
\r
#define ALL_CLIPBOARDS(X)                       \\r
    CROSS_PLATFORM_CLIPBOARDS(X)                \\r
    PLATFORM_CLIPBOARDS(X)                      \\r
    /* end of list */\r
\r
#define CLIP_ID(id,name) id,\r
enum { ALL_CLIPBOARDS(CLIP_ID) N_CLIPBOARDS };\r
#undef CLIP_ID\r
\r
/* Hint from backend to frontend about time-consuming operations, used\r
 * by seat_set_busy_status. Initial state is assumed to be\r
 * BUSY_NOT. */\r
typedef enum BusyStatus {\r
    BUSY_NOT,       /* Not busy, all user interaction OK */\r
    BUSY_WAITING,   /* Waiting for something; local event loops still\r
                       running so some local interaction (e.g. menus)\r
                       OK, but network stuff is suspended */\r
    BUSY_CPU        /* Locally busy (e.g. crypto); user interaction\r
                     * suspended */\r
} BusyStatus;\r
\r
typedef enum SeatInteractionContext {\r
    SIC_BANNER, SIC_KI_PROMPTS\r
} SeatInteractionContext;\r
\r
typedef enum SeatOutputType {\r
    SEAT_OUTPUT_STDOUT, SEAT_OUTPUT_STDERR\r
} SeatOutputType;\r
\r
typedef enum SeatDialogTextType {\r
    SDT_PARA, SDT_DISPLAY, SDT_SCARY_HEADING,\r
    SDT_TITLE, SDT_PROMPT, SDT_BATCH_ABORT,\r
    SDT_MORE_INFO_KEY, SDT_MORE_INFO_VALUE_SHORT, SDT_MORE_INFO_VALUE_BLOB\r
} SeatDialogTextType;\r
struct SeatDialogTextItem {\r
    SeatDialogTextType type;\r
    char *text;\r
};\r
struct SeatDialogText {\r
    size_t nitems, itemsize;\r
    SeatDialogTextItem *items;\r
};\r
SeatDialogText *seat_dialog_text_new(void);\r
void seat_dialog_text_free(SeatDialogText *sdt);\r
PRINTF_LIKE(3, 4) void seat_dialog_text_append(\r
    SeatDialogText *sdt, SeatDialogTextType type, const char *fmt, ...);\r
\r
/*\r
 * Data type 'Seat', which is an API intended to contain essentially\r
 * everything that a back end might need to talk to its client for:\r
 * session output, password prompts, SSH warnings about host keys and\r
 * weak cryptography, notifications of events like the remote process\r
 * exiting or the GUI specials menu needing an update.\r
 */\r
struct Seat {\r
    const struct SeatVtable *vt;\r
};\r
struct SeatVtable {\r
    /*\r
     * Provide output from the remote session. 'type' indicates the\r
     * type of the output (stdout or stderr), which can be used to\r
     * split the output into separate message channels, if the seat\r
     * wants to handle them differently. But combining the channels\r
     * into one is OK too; that's what terminal-window based seats do.\r
     *\r
     * The return value is the current size of the output backlog.\r
     */\r
    size_t (*output)(Seat *seat, SeatOutputType type,\r
                     const void *data, size_t len);\r
\r
    /*\r
     * Called when the back end wants to indicate that EOF has arrived\r
     * on the server-to-client stream. Returns false to indicate that\r
     * we intend to keep the session open in the other direction, or\r
     * true to indicate that if they're closing so are we.\r
     */\r
    bool (*eof)(Seat *seat);\r
\r
    /*\r
     * Called by the back end to notify that the output backlog has\r
     * changed size. A front end in control of the event loop won't\r
     * necessarily need this (they can just keep checking it via\r
     * backend_sendbuffer at every opportunity), but one buried in the\r
     * depths of something else (like an SSH proxy) will need to be\r
     * proactively notified that the amount of buffered data has\r
     * become smaller.\r
     */\r
    void (*sent)(Seat *seat, size_t new_sendbuffer);\r
\r
    /*\r
     * Provide authentication-banner output from the session setup.\r
     * End-user Seats can treat this as very similar to 'output', but\r
     * intermediate Seats in complex proxying situations will want to\r
     * implement this and 'output' differently.\r
     */\r
    size_t (*banner)(Seat *seat, const void *data, size_t len);\r
\r
    /*\r
     * Try to get answers from a set of interactive login prompts. The\r
     * prompts are provided in 'p'.\r
     *\r
     * (FIXME: it would be nice to distinguish two classes of user-\r
     * abort action, so the user could specify 'I want to abandon this\r
     * entire attempt to start a session' or the milder 'I want to\r
     * abandon this particular form of authentication and fall back to\r
     * a different one' - e.g. if you turn out not to be able to\r
     * remember your private key passphrase then perhaps you'd rather\r
     * fall back to password auth rather than aborting the whole\r
     * session.)\r
     */\r
    SeatPromptResult (*get_userpass_input)(Seat *seat, prompts_t *p);\r
\r
    /*\r
     * Notify the seat that the main session channel has been\r
     * successfully set up.\r
     *\r
     * This is only used as part of the SSH proxying system, so it's\r
     * not necessary to implement it in all backends. A backend must\r
     * call this if it advertises the BACKEND_NOTIFIES_SESSION_START\r
     * flag, and otherwise, doesn't have to.\r
     */\r
    void (*notify_session_started)(Seat *seat);\r
\r
    /*\r
     * Notify the seat that the process running at the other end of\r
     * the connection has finished.\r
     */\r
    void (*notify_remote_exit)(Seat *seat);\r
\r
    /*\r
     * Notify the seat that the whole connection has finished.\r
     * (Distinct from notify_remote_exit, e.g. in the case where you\r
     * have port forwardings still active when the main foreground\r
     * session goes away: then you'd get notify_remote_exit when the\r
     * foreground session dies, but notify_remote_disconnect when the\r
     * last forwarding vanishes and the network connection actually\r
     * closes.)\r
     *\r
     * This function might be called multiple times by accident; seats\r
     * should be prepared to cope.\r
     *\r
     * More precisely: this function notifies the seat that\r
     * backend_connected() might now return false where previously it\r
     * returned true. (Note the 'might': an accidental duplicate call\r
     * might happen when backend_connected() was already returning\r
     * false. Or even, in weird situations, when it hadn't stopped\r
     * returning true yet. The point is, when you get this\r
     * notification, all it's really telling you is that it's worth\r
     * _checking_ backend_connected, if you weren't already.)\r
     */\r
    void (*notify_remote_disconnect)(Seat *seat);\r
\r
    /*\r
     * Notify the seat that the connection has suffered a fatal error.\r
     */\r
    void (*connection_fatal)(Seat *seat, const char *message);\r
\r
    /*\r
     * Notify the seat that the list of special commands available\r
     * from backend_get_specials() has changed, so that it might want\r
     * to call that function to repopulate its menu.\r
     *\r
     * Seats are not expected to call backend_get_specials()\r
     * proactively; they may start by assuming that the backend\r
     * provides no special commands at all, so if the backend does\r
     * provide any, then it should use this notification at startup\r
     * time. Of course it can also invoke it later if the set of\r
     * special commands changes.\r
     *\r
     * It does not need to invoke it at session shutdown.\r
     */\r
    void (*update_specials_menu)(Seat *seat);\r
\r
    /*\r
     * Get the seat's preferred value for an SSH terminal mode\r
     * setting. Returning NULL indicates no preference (i.e. the SSH\r
     * connection will not attempt to set the mode at all).\r
     *\r
     * The returned value is dynamically allocated, and the caller\r
     * should free it.\r
     */\r
    char *(*get_ttymode)(Seat *seat, const char *mode);\r
\r
    /*\r
     * Tell the seat whether the backend is currently doing anything\r
     * CPU-intensive (typically a cryptographic key exchange). See\r
     * BusyStatus enumeration above.\r
     */\r
    void (*set_busy_status)(Seat *seat, BusyStatus status);\r
\r
    /*\r
     * Ask the seat whether a given SSH host key should be accepted.\r
     * This is called after we've already checked it by any means we\r
     * can do ourselves, such as checking against host key\r
     * fingerprints in the Conf or the host key cache on disk: once we\r
     * call this function, we've already decided there's nothing for\r
     * it but to prompt the user.\r
     *\r
     * 'mismatch' reports the result of checking the host key cache:\r
     * it is true if the server has presented a host key different\r
     * from the one we expected, and false if we had no expectation in\r
     * the first place.\r
     *\r
     * This call may prompt the user synchronously and not return\r
     * until the answer is available, or it may present the prompt and\r
     * return immediately, giving the answer later via the provided\r
     * callback.\r
     *\r
     * Return values:\r
     *\r
     *  - +1 means `user approved the key, so continue with the\r
     *    connection'\r
     *\r
     *  - 0 means `user rejected the key, abandon the connection'\r
     *\r
     *  - -1 means `I've initiated enquiries, please wait to be called\r
     *    back via the provided function with a result that's either 0\r
     *    or +1'.\r
     */\r
    SeatPromptResult (*confirm_ssh_host_key)(\r
        Seat *seat, const char *host, int port, const char *keytype,\r
        char *keystr, SeatDialogText *text, HelpCtx helpctx,\r
        void (*callback)(void *ctx, SeatPromptResult result), void *ctx);\r
\r
    /*\r
     * Check with the seat whether it's OK to use a cryptographic\r
     * primitive from below the 'warn below this line' threshold in\r
     * the input Conf. Return values are the same as\r
     * confirm_ssh_host_key above.\r
     */\r
    SeatPromptResult (*confirm_weak_crypto_primitive)(\r
        Seat *seat, SeatDialogText *text,\r
        void (*callback)(void *ctx, SeatPromptResult result), void *ctx);\r
\r
    /*\r
     * Variant form of confirm_weak_crypto_primitive, which prints a\r
     * slightly different message but otherwise has the same\r
     * semantics.\r
     *\r
     * This form is used in the case where we're using a host key\r
     * below the warning threshold because that's the best one we have\r
     * cached, but at least one host key algorithm *above* the\r
     * threshold is available that we don't have cached.\r
     */\r
    SeatPromptResult (*confirm_weak_cached_hostkey)(\r
        Seat *seat, SeatDialogText *text,\r
        void (*callback)(void *ctx, SeatPromptResult result), void *ctx);\r
\r
    /*\r
     * Some snippets of text describing the UI actions in host key\r
     * prompts / dialog boxes, to be used in ssh/common.c when it\r
     * assembles the full text of those prompts.\r
     */\r
    const SeatDialogPromptDescriptions *(*prompt_descriptions)(Seat *seat);\r
\r
    /*\r
     * Indicates whether the seat is expecting to interact with the\r
     * user in the UTF-8 character set. (Affects e.g. visual erase\r
     * handling in local line editing.)\r
     */\r
    bool (*is_utf8)(Seat *seat);\r
\r
    /*\r
     * Notify the seat that the back end, and/or the ldisc between\r
     * them, have changed their idea of whether they currently want\r
     * local echo and/or local line editing enabled.\r
     */\r
    void (*echoedit_update)(Seat *seat, bool echoing, bool editing);\r
\r
    /*\r
     * Return the local X display string relevant to a seat, or NULL\r
     * if there isn't one or if the concept is meaningless.\r
     */\r
    const char *(*get_x_display)(Seat *seat);\r
\r
    /*\r
     * Return the X11 id of the X terminal window relevant to a seat,\r
     * by returning true and filling in the output pointer. Return\r
     * false if there isn't one or if the concept is meaningless.\r
     */\r
    bool (*get_windowid)(Seat *seat, long *id_out);\r
\r
    /*\r
     * Return the size of the terminal window in pixels. If the\r
     * concept is meaningless or the information is unavailable,\r
     * return false; otherwise fill in the output pointers and return\r
     * true.\r
     */\r
    bool (*get_window_pixel_size)(Seat *seat, int *width, int *height);\r
\r
    /*\r
     * Return a StripCtrlChars appropriate for sanitising untrusted\r
     * terminal data (e.g. SSH banners, prompts) being sent to the\r
     * user of this seat. May return NULL if no sanitisation is\r
     * needed.\r
     */\r
    StripCtrlChars *(*stripctrl_new)(\r
        Seat *seat, BinarySink *bs_out, SeatInteractionContext sic);\r
\r
    /*\r
     * Set the seat's current idea of where output is coming from.\r
     * True means that output is being generated by our own code base\r
     * (and hence, can be trusted if it's asking you for secrets such\r
     * as your passphrase); false means output is coming from the\r
     * server.\r
     */\r
    void (*set_trust_status)(Seat *seat, bool trusted);\r
\r
    /*\r
     * Query whether this Seat can do anything user-visible in\r
     * response to set_trust_status.\r
     *\r
     * Returns true if the seat has a way to indicate this\r
     * distinction. Returns false if not, in which case the backend\r
     * should use a fallback defence against spoofing of PuTTY's local\r
     * prompts by malicious servers.\r
     */\r
    bool (*can_set_trust_status)(Seat *seat);\r
\r
    /*\r
     * Query whether this Seat's interactive prompt responses and its\r
     * session input come from the same place.\r
     *\r
     * If false, this is used to suppress the final 'Press Return to\r
     * begin session' anti-spoofing prompt in Plink. For example,\r
     * Plink itself sets this flag if its standard input is redirected\r
     * (and therefore not coming from the same place as the console\r
     * it's sending its prompts to).\r
     */\r
    bool (*has_mixed_input_stream)(Seat *seat);\r
\r
    /*\r
     * Ask the seat whether it would like verbose messages.\r
     */\r
    bool (*verbose)(Seat *seat);\r
\r
    /*\r
     * Ask the seat whether it's an interactive program.\r
     */\r
    bool (*interactive)(Seat *seat);\r
\r
    /*\r
     * Return the seat's current idea of where the output cursor is.\r
     *\r
     * Returns true if the seat has a cursor. Returns false if not.\r
     */\r
    bool (*get_cursor_position)(Seat *seat, int *x, int *y);\r
};\r
\r
static inline size_t seat_output(\r
    Seat *seat, SeatOutputType type, const void *data, size_t len)\r
{ return seat->vt->output(seat, type, data, len); }\r
static inline bool seat_eof(Seat *seat)\r
{ return seat->vt->eof(seat); }\r
static inline void seat_sent(Seat *seat, size_t bufsize)\r
{ seat->vt->sent(seat, bufsize); }\r
static inline size_t seat_banner(\r
    InteractionReadySeat iseat, const void *data, size_t len)\r
{ return iseat.seat->vt->banner(iseat.seat, data, len); }\r
static inline SeatPromptResult seat_get_userpass_input(\r
    InteractionReadySeat iseat, prompts_t *p)\r
{ return iseat.seat->vt->get_userpass_input(iseat.seat, p); }\r
static inline void seat_notify_session_started(Seat *seat)\r
{ seat->vt->notify_session_started(seat); }\r
static inline void seat_notify_remote_exit(Seat *seat)\r
{ seat->vt->notify_remote_exit(seat); }\r
static inline void seat_notify_remote_disconnect(Seat *seat)\r
{ seat->vt->notify_remote_disconnect(seat); }\r
static inline void seat_update_specials_menu(Seat *seat)\r
{ seat->vt->update_specials_menu(seat); }\r
static inline char *seat_get_ttymode(Seat *seat, const char *mode)\r
{ return seat->vt->get_ttymode(seat, mode); }\r
static inline void seat_set_busy_status(Seat *seat, BusyStatus status)\r
{ seat->vt->set_busy_status(seat, status); }\r
static inline SeatPromptResult seat_confirm_ssh_host_key(\r
    InteractionReadySeat iseat, const char *h, int p, const char *ktyp,\r
    char *kstr, SeatDialogText *text, HelpCtx helpctx,\r
    void (*cb)(void *ctx, SeatPromptResult result), void *ctx)\r
{ return iseat.seat->vt->confirm_ssh_host_key(\r
        iseat.seat, h, p, ktyp, kstr, text, helpctx, cb, ctx); }\r
static inline SeatPromptResult seat_confirm_weak_crypto_primitive(\r
    InteractionReadySeat iseat, SeatDialogText *text,\r
    void (*cb)(void *ctx, SeatPromptResult result), void *ctx)\r
{ return iseat.seat->vt->confirm_weak_crypto_primitive(\r
        iseat.seat, text, cb, ctx); }\r
static inline SeatPromptResult seat_confirm_weak_cached_hostkey(\r
    InteractionReadySeat iseat, SeatDialogText *text,\r
    void (*cb)(void *ctx, SeatPromptResult result), void *ctx)\r
{ return iseat.seat->vt->confirm_weak_cached_hostkey(\r
        iseat.seat, text, cb, ctx); }\r
static inline const SeatDialogPromptDescriptions *seat_prompt_descriptions(\r
    Seat *seat)\r
{ return seat->vt->prompt_descriptions(seat); }\r
static inline bool seat_is_utf8(Seat *seat)\r
{ return seat->vt->is_utf8(seat); }\r
static inline void seat_echoedit_update(Seat *seat, bool ec, bool ed)\r
{ seat->vt->echoedit_update(seat, ec, ed); }\r
static inline const char *seat_get_x_display(Seat *seat)\r
{ return seat->vt->get_x_display(seat); }\r
static inline bool seat_get_windowid(Seat *seat, long *id_out)\r
{ return seat->vt->get_windowid(seat, id_out); }\r
static inline bool seat_get_window_pixel_size(Seat *seat, int *w, int *h)\r
{ return seat->vt->get_window_pixel_size(seat, w, h); }\r
static inline StripCtrlChars *seat_stripctrl_new(\r
    Seat *seat, BinarySink *bs, SeatInteractionContext sic)\r
{ return seat->vt->stripctrl_new(seat, bs, sic); }\r
static inline void seat_set_trust_status(Seat *seat, bool trusted)\r
{ seat->vt->set_trust_status(seat, trusted); }\r
static inline bool seat_can_set_trust_status(Seat *seat)\r
{ return seat->vt->can_set_trust_status(seat); }\r
static inline bool seat_has_mixed_input_stream(Seat *seat)\r
{ return seat->vt->has_mixed_input_stream(seat); }\r
static inline bool seat_verbose(Seat *seat)\r
{ return seat->vt->verbose(seat); }\r
static inline bool seat_interactive(Seat *seat)\r
{ return seat->vt->interactive(seat); }\r
static inline bool seat_get_cursor_position(Seat *seat, int *x, int *y)\r
{ return  seat->vt->get_cursor_position(seat, x, y); }\r
\r
/* Unlike the seat's actual method, the public entry point\r
 * seat_connection_fatal is a wrapper function with a printf-like API,\r
 * defined in utils. */\r
void seat_connection_fatal(Seat *seat, const char *fmt, ...) PRINTF_LIKE(2, 3);\r
\r
/* Handy aliases for seat_output which set is_stderr to a fixed value. */\r
static inline size_t seat_stdout(Seat *seat, const void *data, size_t len)\r
{ return seat_output(seat, SEAT_OUTPUT_STDOUT, data, len); }\r
static inline size_t seat_stdout_pl(Seat *seat, ptrlen data)\r
{ return seat_output(seat, SEAT_OUTPUT_STDOUT, data.ptr, data.len); }\r
static inline size_t seat_stderr(Seat *seat, const void *data, size_t len)\r
{ return seat_output(seat, SEAT_OUTPUT_STDERR, data, len); }\r
static inline size_t seat_stderr_pl(Seat *seat, ptrlen data)\r
{ return seat_output(seat, SEAT_OUTPUT_STDERR, data.ptr, data.len); }\r
\r
/* Alternative API for seat_banner taking a ptrlen */\r
static inline size_t seat_banner_pl(InteractionReadySeat iseat, ptrlen data)\r
{ return iseat.seat->vt->banner(iseat.seat, data.ptr, data.len); }\r
\r
struct SeatDialogPromptDescriptions {\r
    const char *hk_accept_action;\r
    const char *hk_connect_once_action;\r
    const char *hk_cancel_action, *hk_cancel_action_Participle;\r
    const char *weak_accept_action, *weak_cancel_action;\r
};\r
\r
/* In the utils subdir: print a message to the Seat which can't be\r
 * spoofed by server-supplied auth-time output such as SSH banners */\r
void seat_antispoof_msg(InteractionReadySeat iseat, const char *msg);\r
\r
/*\r
 * Stub methods for seat implementations that want to use the obvious\r
 * null handling for a given method.\r
 *\r
 * These are generally obvious, except for is_utf8, where you might\r
 * plausibly want to return either fixed answer 'no' or 'yes'.\r
 */\r
size_t nullseat_output(\r
    Seat *seat, SeatOutputType type, const void *data, size_t len);\r
bool nullseat_eof(Seat *seat);\r
void nullseat_sent(Seat *seat, size_t bufsize);\r
size_t nullseat_banner(Seat *seat, const void *data, size_t len);\r
size_t nullseat_banner_to_stderr(Seat *seat, const void *data, size_t len);\r
SeatPromptResult nullseat_get_userpass_input(Seat *seat, prompts_t *p);\r
void nullseat_notify_session_started(Seat *seat);\r
void nullseat_notify_remote_exit(Seat *seat);\r
void nullseat_notify_remote_disconnect(Seat *seat);\r
void nullseat_connection_fatal(Seat *seat, const char *message);\r
void nullseat_update_specials_menu(Seat *seat);\r
char *nullseat_get_ttymode(Seat *seat, const char *mode);\r
void nullseat_set_busy_status(Seat *seat, BusyStatus status);\r
SeatPromptResult nullseat_confirm_ssh_host_key(\r
    Seat *seat, const char *host, int port, const char *keytype,\r
    char *keystr, SeatDialogText *text, HelpCtx helpctx,\r
    void (*callback)(void *ctx, SeatPromptResult result), void *ctx);\r
SeatPromptResult nullseat_confirm_weak_crypto_primitive(\r
    Seat *seat, SeatDialogText *text,\r
    void (*callback)(void *ctx, SeatPromptResult result), void *ctx);\r
SeatPromptResult nullseat_confirm_weak_cached_hostkey(\r
    Seat *seat, SeatDialogText *text,\r
    void (*callback)(void *ctx, SeatPromptResult result), void *ctx);\r
const SeatDialogPromptDescriptions *nullseat_prompt_descriptions(Seat *seat);\r
bool nullseat_is_never_utf8(Seat *seat);\r
bool nullseat_is_always_utf8(Seat *seat);\r
void nullseat_echoedit_update(Seat *seat, bool echoing, bool editing);\r
const char *nullseat_get_x_display(Seat *seat);\r
bool nullseat_get_windowid(Seat *seat, long *id_out);\r
bool nullseat_get_window_pixel_size(Seat *seat, int *width, int *height);\r
StripCtrlChars *nullseat_stripctrl_new(\r
    Seat *seat, BinarySink *bs_out, SeatInteractionContext sic);\r
void nullseat_set_trust_status(Seat *seat, bool trusted);\r
bool nullseat_can_set_trust_status_yes(Seat *seat);\r
bool nullseat_can_set_trust_status_no(Seat *seat);\r
bool nullseat_has_mixed_input_stream_yes(Seat *seat);\r
bool nullseat_has_mixed_input_stream_no(Seat *seat);\r
bool nullseat_verbose_no(Seat *seat);\r
bool nullseat_verbose_yes(Seat *seat);\r
bool nullseat_interactive_no(Seat *seat);\r
bool nullseat_interactive_yes(Seat *seat);\r
bool nullseat_get_cursor_position(Seat *seat, int *x, int *y);\r
\r
/*\r
 * Seat functions provided by the platform's console-application\r
 * support module (console.c in each platform subdirectory).\r
 */\r
\r
void console_connection_fatal(Seat *seat, const char *message);\r
SeatPromptResult console_confirm_ssh_host_key(\r
    Seat *seat, const char *host, int port, const char *keytype,\r
    char *keystr, SeatDialogText *text, HelpCtx helpctx,\r
    void (*callback)(void *ctx, SeatPromptResult result), void *ctx);\r
SeatPromptResult console_confirm_weak_crypto_primitive(\r
    Seat *seat, SeatDialogText *text,\r
    void (*callback)(void *ctx, SeatPromptResult result), void *ctx);\r
SeatPromptResult console_confirm_weak_cached_hostkey(\r
    Seat *seat, SeatDialogText *text,\r
    void (*callback)(void *ctx, SeatPromptResult result), void *ctx);\r
StripCtrlChars *console_stripctrl_new(\r
    Seat *seat, BinarySink *bs_out, SeatInteractionContext sic);\r
void console_set_trust_status(Seat *seat, bool trusted);\r
bool console_can_set_trust_status(Seat *seat);\r
bool console_has_mixed_input_stream(Seat *seat);\r
const SeatDialogPromptDescriptions *console_prompt_descriptions(Seat *seat);\r
\r
/*\r
 * Other centralised seat functions.\r
 */\r
SeatPromptResult filexfer_get_userpass_input(Seat *seat, prompts_t *p);\r
bool cmdline_seat_verbose(Seat *seat);\r
\r
/*\r
 * TempSeat: a seat implementation that can be given to a backend\r
 * temporarily while network proxy setup is using the real seat.\r
 * Buffers output and trust-status changes until the real seat is\r
 * available again.\r
 */\r
\r
/* Called by the proxy code to make a TempSeat. */\r
Seat *tempseat_new(Seat *real);\r
\r
/* Query functions to tell if a Seat _is_ temporary, and if so, to\r
 * return the underlying real Seat. */\r
bool is_tempseat(Seat *seat);\r
Seat *tempseat_get_real(Seat *seat);\r
\r
/* Called by interactor_return_seat once the proxy connection has\r
 * finished setting up (or failed), to pass on any buffered stuff to\r
 * the real seat. */\r
void tempseat_flush(Seat *ts);\r
\r
/* Frees a TempSeat, without flushing anything it has buffered. (Call\r
 * this after tempseat_flush, or alternatively, when you were going to\r
 * abandon the whole connection anyway.) */\r
void tempseat_free(Seat *ts);\r
\r
typedef struct rgb {\r
    uint8_t r, g, b;\r
} rgb;\r
\r
/*\r
 * Data type 'TermWin', which is a vtable encapsulating all the\r
 * functionality that Terminal expects from its containing terminal\r
 * window.\r
 */\r
struct TermWin {\r
    const struct TermWinVtable *vt;\r
};\r
struct TermWinVtable {\r
    /*\r
     * All functions listed here between setup_draw_ctx and\r
     * free_draw_ctx expect to be _called_ between them too, so that\r
     * the TermWin has a drawing context currently available.\r
     *\r
     * (Yes, even char_width, because e.g. the Windows implementation\r
     * of TermWin handles it by loading the currently configured font\r
     * into the HDC and doing a GDI query.)\r
     */\r
    bool (*setup_draw_ctx)(TermWin *);\r
    /* Draw text in the window, during a painting operation */\r
    void (*draw_text)(TermWin *, int x, int y, wchar_t *text, int len,\r
                      unsigned long attrs, int line_attrs, truecolour tc);\r
    /* Draw the visible cursor. Expects you to have called do_text\r
     * first (because it might just draw an underline over a character\r
     * presumed to exist already), but also expects you to pass in all\r
     * the details of the character under the cursor (because it might\r
     * redraw it in different colours). */\r
    void (*draw_cursor)(TermWin *, int x, int y, wchar_t *text, int len,\r
                        unsigned long attrs, int line_attrs, truecolour tc);\r
    /* Draw the sigil indicating that a line of text has come from\r
     * PuTTY itself rather than the far end (defence against end-of-\r
     * authentication spoofing) */\r
    void (*draw_trust_sigil)(TermWin *, int x, int y);\r
    int (*char_width)(TermWin *, int uc);\r
    void (*free_draw_ctx)(TermWin *);\r
\r
    void (*set_cursor_pos)(TermWin *, int x, int y);\r
\r
    /* set_raw_mouse_mode instructs the front end to start sending mouse events\r
     * in raw mode suitable for translating into mouse-tracking terminal data\r
     * (e.g. include scroll-wheel events and don't bother to identify double-\r
     * and triple-clicks). set_raw_mouse_mode_pointer instructs the front end\r
     * to change the mouse pointer shape to *indicate* raw mouse mode. */\r
    void (*set_raw_mouse_mode)(TermWin *, bool enable);\r
    void (*set_raw_mouse_mode_pointer)(TermWin *, bool enable);\r
\r
    void (*set_scrollbar)(TermWin *, int total, int start, int page);\r
\r
    void (*bell)(TermWin *, int mode);\r
\r
    void (*clip_write)(TermWin *, int clipboard, wchar_t *text, int *attrs,\r
                       truecolour *colours, int len, bool must_deselect);\r
    void (*clip_request_paste)(TermWin *, int clipboard);\r
\r
    void (*refresh)(TermWin *);\r
\r
    /* request_resize asks the front end if the terminal can please be\r
     * resized to (w,h) in characters. The front end MAY call\r
     * term_size() in response to tell the terminal its new size\r
     * (which MAY be the requested size, or some other size if the\r
     * requested one can't be achieved). The front end MAY also not\r
     * call term_size() at all. But the front end MUST reply to this\r
     * request by calling term_resize_request_completed(), after the\r
     * responding resize event has taken place (if any).\r
     *\r
     * The calls to term_size and term_resize_request_completed may be\r
     * synchronous callbacks from within the call to request_resize(). */\r
    void (*request_resize)(TermWin *, int w, int h);\r
\r
    void (*set_title)(TermWin *, const char *title, int codepage);\r
    void (*set_icon_title)(TermWin *, const char *icontitle, int codepage);\r
\r
    /* set_minimised and set_maximised are assumed to set two\r
     * independent settings, rather than a single three-way\r
     * {min,normal,max} switch. The idea is that when you un-minimise\r
     * the window it remembers whether to go back to normal or\r
     * maximised. */\r
    void (*set_minimised)(TermWin *, bool minimised);\r
    void (*set_maximised)(TermWin *, bool maximised);\r
    void (*move)(TermWin *, int x, int y);\r
    void (*set_zorder)(TermWin *, bool top);\r
\r
    /* Set the colour palette that the TermWin will use to display\r
     * text. One call to this function sets 'ncolours' consecutive\r
     * colours in the OSC 4 sequence, starting at 'start'. */\r
    void (*palette_set)(TermWin *, unsigned start, unsigned ncolours,\r
                        const rgb *colours);\r
\r
    /* Query the front end for any OS-local overrides to the default\r
     * colours stored in Conf. The front end should set any it cares\r
     * about by calling term_palette_override.\r
     *\r
     * The Terminal object is passed in as a parameter, because this\r
     * can be called as a callback from term_init(). So the TermWin\r
     * itself won't yet have been told where to find its Terminal\r
     * object, because that doesn't happen until term_init\r
     * returns. */\r
    void (*palette_get_overrides)(TermWin *, Terminal *);\r
\r
    /* Notify the front end that the terminal's buffer of unprocessed\r
     * output has reduced. (Front ends will likely pass this straight\r
     * on to backend_unthrottle.) */\r
    void (*unthrottle)(TermWin *, size_t bufsize);\r
};\r
\r
static inline bool win_setup_draw_ctx(TermWin *win)\r
{ return win->vt->setup_draw_ctx(win); }\r
static inline void win_draw_text(\r
    TermWin *win, int x, int y, wchar_t *text, int len,\r
    unsigned long attrs, int line_attrs, truecolour tc)\r
{ win->vt->draw_text(win, x, y, text, len, attrs, line_attrs, tc); }\r
static inline void win_draw_cursor(\r
    TermWin *win, int x, int y, wchar_t *text, int len,\r
    unsigned long attrs, int line_attrs, truecolour tc)\r
{ win->vt->draw_cursor(win, x, y, text, len, attrs, line_attrs, tc); }\r
static inline void win_draw_trust_sigil(TermWin *win, int x, int y)\r
{ win->vt->draw_trust_sigil(win, x, y); }\r
static inline int win_char_width(TermWin *win, int uc)\r
{ return win->vt->char_width(win, uc); }\r
static inline void win_free_draw_ctx(TermWin *win)\r
{ win->vt->free_draw_ctx(win); }\r
static inline void win_set_cursor_pos(TermWin *win, int x, int y)\r
{ win->vt->set_cursor_pos(win, x, y); }\r
static inline void win_set_raw_mouse_mode(TermWin *win, bool enable)\r
{ win->vt->set_raw_mouse_mode(win, enable); }\r
static inline void win_set_raw_mouse_mode_pointer(TermWin *win, bool enable)\r
{ win->vt->set_raw_mouse_mode_pointer(win, enable); }\r
static inline void win_set_scrollbar(TermWin *win, int t, int s, int p)\r
{ win->vt->set_scrollbar(win, t, s, p); }\r
static inline void win_bell(TermWin *win, int mode)\r
{ win->vt->bell(win, mode); }\r
static inline void win_clip_write(\r
    TermWin *win, int clipboard, wchar_t *text, int *attrs,\r
    truecolour *colours, int len, bool deselect)\r
{ win->vt->clip_write(win, clipboard, text, attrs, colours, len, deselect); }\r
static inline void win_clip_request_paste(TermWin *win, int clipboard)\r
{ win->vt->clip_request_paste(win, clipboard); }\r
static inline void win_refresh(TermWin *win)\r
{ win->vt->refresh(win); }\r
static inline void win_request_resize(TermWin *win, int w, int h)\r
{ win->vt->request_resize(win, w, h); }\r
static inline void win_set_title(TermWin *win, const char *title, int codepage)\r
{ win->vt->set_title(win, title, codepage); }\r
static inline void win_set_icon_title(TermWin *win, const char *icontitle,\r
                                      int codepage)\r
{ win->vt->set_icon_title(win, icontitle, codepage); }\r
static inline void win_set_minimised(TermWin *win, bool minimised)\r
{ win->vt->set_minimised(win, minimised); }\r
static inline void win_set_maximised(TermWin *win, bool maximised)\r
{ win->vt->set_maximised(win, maximised); }\r
static inline void win_move(TermWin *win, int x, int y)\r
{ win->vt->move(win, x, y); }\r
static inline void win_set_zorder(TermWin *win, bool top)\r
{ win->vt->set_zorder(win, top); }\r
static inline void win_palette_set(\r
    TermWin *win, unsigned start, unsigned ncolours, const rgb *colours)\r
{ win->vt->palette_set(win, start, ncolours, colours); }\r
static inline void win_palette_get_overrides(TermWin *win, Terminal *term)\r
{ win->vt->palette_get_overrides(win, term); }\r
static inline void win_unthrottle(TermWin *win, size_t size)\r
{ win->vt->unthrottle(win, size); }\r
\r
/*\r
 * Global functions not specific to a connection instance.\r
 */\r
void nonfatal(const char *, ...) PRINTF_LIKE(1, 2);\r
NORETURN void modalfatalbox(const char *, ...) PRINTF_LIKE(1, 2);\r
NORETURN void cleanup_exit(int);\r
\r
/*\r
 * Exports from conf.c, and a big enum (via parametric macro) of\r
 * configuration option keys.\r
 */\r
#define CONFIG_OPTIONS(X) \\r
    /* X(value-type, subkey-type, keyword) */ \\r
    X(STR, NONE, host) \\r
    X(INT, NONE, port) \\r
    X(INT, NONE, protocol) /* PROT_SSH, PROT_TELNET etc */ \\r
    X(INT, NONE, addressfamily) /* ADDRTYPE_IPV[46] or ADDRTYPE_UNSPEC */ \\r
    X(INT, NONE, close_on_exit) /* FORCE_ON, FORCE_OFF, AUTO */ \\r
    X(BOOL, NONE, warn_on_close) \\r
    X(INT, NONE, ping_interval) /* in seconds */ \\r
    X(BOOL, NONE, tcp_nodelay) \\r
    X(BOOL, NONE, tcp_keepalives) \\r
    X(STR, NONE, loghost) /* logical host being contacted, for host key check */ \\r
    /* Proxy options */ \\r
    X(STR, NONE, proxy_exclude_list) \\r
    X(INT, NONE, proxy_dns) /* FORCE_ON, FORCE_OFF, AUTO */ \\r
    X(BOOL, NONE, even_proxy_localhost) \\r
    X(INT, NONE, proxy_type) /* PROXY_NONE, PROXY_SOCKS4, ... */ \\r
    X(STR, NONE, proxy_host) \\r
    X(INT, NONE, proxy_port) \\r
    X(STR, NONE, proxy_username) \\r
    X(STR, NONE, proxy_password) \\r
    X(STR, NONE, proxy_telnet_command) \\r
    X(INT, NONE, proxy_log_to_term) /* FORCE_ON, FORCE_OFF, AUTO */ \\r
    /* SSH options */ \\r
    X(STR, NONE, remote_cmd) \\r
    X(STR, NONE, remote_cmd2) /* fallback if remote_cmd fails; never loaded or saved */ \\r
    X(BOOL, NONE, nopty) \\r
    X(BOOL, NONE, compression) \\r
    X(INT, INT, ssh_kexlist) \\r
    X(INT, INT, ssh_hklist) \\r
    X(BOOL, NONE, ssh_prefer_known_hostkeys) \\r
    X(INT, NONE, ssh_rekey_time) /* in minutes */ \\r
    X(STR, NONE, ssh_rekey_data) /* string encoding e.g. "100K", "2M", "1G" */ \\r
    X(BOOL, NONE, tryagent) \\r
    X(BOOL, NONE, agentfwd) \\r
    X(BOOL, NONE, change_username) /* allow username switching in SSH-2 */ \\r
    X(INT, INT, ssh_cipherlist) \\r
    X(FILENAME, NONE, keyfile) \\r
    X(FILENAME, NONE, detached_cert) \\r
    X(STR, NONE, auth_plugin) \\r
    /* \\r
     * Which SSH protocol to use. \\r
     * For historical reasons, the current legal values for CONF_sshprot \\r
     * are: \\r
     *  0 = SSH-1 only \\r
     *  3 = SSH-2 only \\r
     * We used to also support \\r
     *  1 = SSH-1 with fallback to SSH-2 \\r
     *  2 = SSH-2 with fallback to SSH-1 \\r
     * and we continue to use 0/3 in storage formats rather than the more \\r
     * obvious 1/2 to avoid surprises if someone saves a session and later \\r
     * downgrades PuTTY. So it's easier to use these numbers internally too. \\r
     */ \\r
    X(INT, NONE, sshprot) \\r
    X(BOOL, NONE, ssh2_des_cbc) /* "des-cbc" unrecommended SSH-2 cipher */ \\r
    X(BOOL, NONE, ssh_no_userauth) /* bypass "ssh-userauth" (SSH-2 only) */ \\r
    X(BOOL, NONE, ssh_no_trivial_userauth) /* disable trivial types of auth */ \\r
    X(BOOL, NONE, ssh_show_banner) /* show USERAUTH_BANNERs (SSH-2 only) */ \\r
    X(BOOL, NONE, try_tis_auth) \\r
    X(BOOL, NONE, try_ki_auth) \\r
    X(BOOL, NONE, try_gssapi_auth) /* attempt gssapi auth via ssh userauth */ \\r
    X(BOOL, NONE, try_gssapi_kex) /* attempt gssapi auth via ssh kex */ \\r
    X(BOOL, NONE, gssapifwd) /* forward tgt via gss */ \\r
    X(INT, NONE, gssapirekey) /* KEXGSS refresh interval (mins) */ \\r
    X(INT, INT, ssh_gsslist) /* preference order for local GSS libs */ \\r
    X(FILENAME, NONE, ssh_gss_custom) \\r
    X(BOOL, NONE, ssh_subsys) /* run a subsystem rather than a command */ \\r
    X(BOOL, NONE, ssh_subsys2) /* fallback to go with remote_cmd_ptr2 */ \\r
    X(BOOL, NONE, ssh_no_shell) /* avoid running a shell */ \\r
    X(STR, NONE, ssh_nc_host) /* host to connect to in `nc' mode */ \\r
    X(INT, NONE, ssh_nc_port) /* port to connect to in `nc' mode */ \\r
    /* Telnet options */ \\r
    X(STR, NONE, termtype) \\r
    X(STR, NONE, termspeed) \\r
    X(STR, STR, ttymodes) /* values are "Vvalue" or "A" */ \\r
    X(STR, STR, environmt) \\r
    X(STR, NONE, username) \\r
    X(BOOL, NONE, username_from_env) \\r
    X(STR, NONE, localusername) \\r
    X(BOOL, NONE, rfc_environ) \\r
    X(BOOL, NONE, passive_telnet) \\r
    /* Serial port options */ \\r
    X(STR, NONE, serline) \\r
    X(INT, NONE, serspeed) \\r
    X(INT, NONE, serdatabits) \\r
    X(INT, NONE, serstopbits) \\r
    X(INT, NONE, serparity) /* SER_PAR_NONE, SER_PAR_ODD, ... */ \\r
    X(INT, NONE, serflow) /* SER_FLOW_NONE, SER_FLOW_XONXOFF, ... */ \\r
    /* Supdup options */ \\r
    X(STR, NONE, supdup_location) \\r
    X(INT, NONE, supdup_ascii_set) \\r
    X(BOOL, NONE, supdup_more) \\r
    X(BOOL, NONE, supdup_scroll) \\r
    /* Keyboard options */ \\r
    X(BOOL, NONE, bksp_is_delete) \\r
    X(BOOL, NONE, rxvt_homeend) \\r
    X(INT, NONE, funky_type) /* FUNKY_XTERM, FUNKY_LINUX, ... */ \\r
    X(INT, NONE, sharrow_type) /* SHARROW_APPLICATION, SHARROW_BITMAP, ... */ \\r
    X(BOOL, NONE, no_applic_c) /* totally disable app cursor keys */ \\r
    X(BOOL, NONE, no_applic_k) /* totally disable app keypad */ \\r
    X(BOOL, NONE, no_mouse_rep) /* totally disable mouse reporting */ \\r
    X(BOOL, NONE, no_remote_resize) /* disable remote resizing */ \\r
    X(BOOL, NONE, no_alt_screen) /* disable alternate screen */ \\r
    X(BOOL, NONE, no_remote_wintitle) /* disable remote retitling */ \\r
    X(BOOL, NONE, no_remote_clearscroll) /* disable ESC[3J */ \\r
    X(BOOL, NONE, no_dbackspace) /* disable destructive backspace */ \\r
    X(BOOL, NONE, no_remote_charset) /* disable remote charset config */ \\r
    X(INT, NONE, remote_qtitle_action) /* remote win title query action\r
                                       * (TITLE_NONE, TITLE_EMPTY, ...) */ \\r
    X(BOOL, NONE, app_cursor) \\r
    X(BOOL, NONE, app_keypad) \\r
    X(BOOL, NONE, nethack_keypad) \\r
    X(BOOL, NONE, telnet_keyboard) \\r
    X(BOOL, NONE, telnet_newline) \\r
    X(BOOL, NONE, alt_f4) /* is it special? */ \\r
    X(BOOL, NONE, alt_space) /* is it special? */ \\r
    X(BOOL, NONE, alt_only) /* is it special? */ \\r
    X(INT, NONE, localecho) /* FORCE_ON, FORCE_OFF, AUTO */ \\r
    X(INT, NONE, localedit) /* FORCE_ON, FORCE_OFF, AUTO */ \\r
    X(BOOL, NONE, alwaysontop) \\r
    X(BOOL, NONE, fullscreenonaltenter) \\r
    X(BOOL, NONE, scroll_on_key) \\r
    X(BOOL, NONE, scroll_on_disp) \\r
    X(BOOL, NONE, erase_to_scrollback) \\r
    X(BOOL, NONE, compose_key) \\r
    X(BOOL, NONE, ctrlaltkeys) \\r
    X(BOOL, NONE, osx_option_meta) \\r
    X(BOOL, NONE, osx_command_meta) \\r
    X(STR, NONE, wintitle) /* initial window title */ \\r
    /* Terminal options */ \\r
    X(INT, NONE, savelines) \\r
    X(BOOL, NONE, dec_om) \\r
    X(BOOL, NONE, wrap_mode) \\r
    X(BOOL, NONE, lfhascr) \\r
    X(INT, NONE, cursor_type) /* 0=block 1=underline 2=vertical */ \\r
    X(BOOL, NONE, blink_cur) \\r
    X(INT, NONE, beep) /* BELL_DISABLED, BELL_DEFAULT, ... */ \\r
    X(INT, NONE, beep_ind) /* B_IND_DISABLED, B_IND_FLASH, ... */ \\r
    X(BOOL, NONE, bellovl) /* bell overload protection active? */ \\r
    X(INT, NONE, bellovl_n) /* number of bells to cause overload */ \\r
    X(INT, NONE, bellovl_t) /* time interval for overload (seconds) */ \\r
    X(INT, NONE, bellovl_s) /* period of silence to re-enable bell (s) */ \\r
    X(FILENAME, NONE, bell_wavefile) \\r
    X(BOOL, NONE, scrollbar) \\r
    X(BOOL, NONE, scrollbar_in_fullscreen) \\r
    X(INT, NONE, resize_action) /* RESIZE_TERM, RESIZE_DISABLED, ... */ \\r
    X(BOOL, NONE, bce) \\r
    X(BOOL, NONE, blinktext) \\r
    X(BOOL, NONE, win_name_always) \\r
    X(INT, NONE, width) \\r
    X(INT, NONE, height) \\r
    X(FONT, NONE, font) \\r
    X(INT, NONE, font_quality) /* FQ_DEFAULT, FQ_ANTIALIASED, ... */ \\r
    X(FILENAME, NONE, logfilename) \\r
    X(INT, NONE, logtype) /* LGTYP_NONE, LGTYPE_ASCII, ... */ \\r
    X(INT, NONE, logxfovr) /* LGXF_OVR, LGXF_APN, LGXF_ASK */ \\r
    X(BOOL, NONE, logflush) \\r
    X(BOOL, NONE, logheader) \\r
    X(BOOL, NONE, logomitpass) \\r
    X(BOOL, NONE, logomitdata) \\r
    X(BOOL, NONE, hide_mouseptr) \\r
    X(BOOL, NONE, sunken_edge) \\r
    X(INT, NONE, window_border) /* in pixels */ \\r
    X(STR, NONE, answerback) \\r
    X(STR, NONE, printer) \\r
    X(BOOL, NONE, no_arabicshaping) \\r
    X(BOOL, NONE, no_bidi) \\r
    /* Colour options */ \\r
    X(BOOL, NONE, ansi_colour) \\r
    X(BOOL, NONE, xterm_256_colour) \\r
    X(BOOL, NONE, true_colour) \\r
    X(BOOL, NONE, system_colour) \\r
    X(BOOL, NONE, try_palette) \\r
    X(INT, NONE, bold_style) /* 1=font 2=colour (3=both) */ \\r
    X(INT, INT, colours) /* indexed by the CONF_COLOUR_* enum encoding */ \\r
    /* Selection options */ \\r
    X(INT, NONE, mouse_is_xterm) /* 0=compromise 1=xterm 2=Windows */ \\r
    X(BOOL, NONE, rect_select) \\r
    X(BOOL, NONE, paste_controls) \\r
    X(BOOL, NONE, rawcnp) \\r
    X(BOOL, NONE, utf8linedraw) \\r
    X(BOOL, NONE, rtf_paste) \\r
    X(BOOL, NONE, mouse_override) \\r
    X(INT, INT, wordness) \\r
    X(BOOL, NONE, mouseautocopy) \\r
    X(INT, NONE, mousepaste) /* CLIPUI_IMPLICIT, CLIPUI_EXPLICIT, ... */ \\r
    X(INT, NONE, ctrlshiftins) /* CLIPUI_IMPLICIT, CLIPUI_EXPLICIT, ... */ \\r
    X(INT, NONE, ctrlshiftcv) /* CLIPUI_IMPLICIT, CLIPUI_EXPLICIT, ... */ \\r
    X(STR, NONE, mousepaste_custom) \\r
    X(STR, NONE, ctrlshiftins_custom) \\r
    X(STR, NONE, ctrlshiftcv_custom) \\r
    /* translations */ \\r
    X(INT, NONE, vtmode) /* VT_XWINDOWS, VT_OEMANSI, ... */ \\r
    X(STR, NONE, line_codepage) \\r
    X(BOOL, NONE, cjk_ambig_wide) \\r
    X(BOOL, NONE, utf8_override) \\r
    X(BOOL, NONE, xlat_capslockcyr) \\r
    /* X11 forwarding */ \\r
    X(BOOL, NONE, x11_forward) \\r
    X(STR, NONE, x11_display) \\r
    X(INT, NONE, x11_auth) /* X11_NO_AUTH, X11_MIT, X11_XDM */ \\r
    X(FILENAME, NONE, xauthfile) \\r
    /* port forwarding */ \\r
    X(BOOL, NONE, lport_acceptall) /* accept conns from hosts other than localhost */ \\r
    X(BOOL, NONE, rport_acceptall) /* same for remote forwarded ports (SSH-2 only) */ \\r
    /*                                                                \\r
     * Subkeys for 'portfwd' can have the following forms:            \\r
     *                                                                \\r
     *   [LR]localport                                                \\r
     *   [LR]localaddr:localport                                      \\r
     *                                                                \\r
     * Dynamic forwardings are indicated by an 'L' key, and the       \\r
     * special value "D". For all other forwardings, the value        \\r
     * should be of the form 'host:port'.                             \\r
     */ \\r
    X(STR, STR, portfwd) \\r
    /* SSH bug compatibility modes. All FORCE_ON/FORCE_OFF/AUTO */ \\r
    X(INT, NONE, sshbug_ignore1) \\r
    X(INT, NONE, sshbug_plainpw1) \\r
    X(INT, NONE, sshbug_rsa1) \\r
    X(INT, NONE, sshbug_hmac2) \\r
    X(INT, NONE, sshbug_derivekey2) \\r
    X(INT, NONE, sshbug_rsapad2) \\r
    X(INT, NONE, sshbug_pksessid2) \\r
    X(INT, NONE, sshbug_rekey2) \\r
    X(INT, NONE, sshbug_maxpkt2) \\r
    X(INT, NONE, sshbug_ignore2) \\r
    X(INT, NONE, sshbug_oldgex2) \\r
    X(INT, NONE, sshbug_winadj) \\r
    X(INT, NONE, sshbug_chanreq) \\r
    X(INT, NONE, sshbug_dropstart) \\r
    X(INT, NONE, sshbug_filter_kexinit) \\r
    X(INT, NONE, sshbug_rsa_sha2_cert_userauth) \\r
    /*                                                                \\r
     * ssh_simple means that we promise never to open any channel     \\r
     * other than the main one, which means it can safely use a very  \\r
     * large window in SSH-2.                                         \\r
     */ \\r
    X(BOOL, NONE, ssh_simple) \\r
    X(BOOL, NONE, ssh_connection_sharing) \\r
    X(BOOL, NONE, ssh_connection_sharing_upstream) \\r
    X(BOOL, NONE, ssh_connection_sharing_downstream) \\r
    /*\r
     * ssh_manual_hostkeys is conceptually a set rather than a\r
     * dictionary: the string subkeys are the important thing, and the\r
     * actual values to which those subkeys map are all "".\r
     */ \\r
    X(STR, STR, ssh_manual_hostkeys) \\r
    /* Options for pterm. Should split out into platform-dependent part. */ \\r
    X(BOOL, NONE, stamp_utmp) \\r
    X(BOOL, NONE, login_shell) \\r
    X(BOOL, NONE, scrollbar_on_left) \\r
    X(BOOL, NONE, shadowbold) \\r
    X(FONT, NONE, boldfont) \\r
    X(FONT, NONE, widefont) \\r
    X(FONT, NONE, wideboldfont) \\r
    X(INT, NONE, shadowboldoffset) /* in pixels */ \\r
    X(BOOL, NONE, crhaslf) \\r
    X(STR, NONE, winclass) \\r
    /* end of list */\r
\r
/* Now define the actual enum of option keywords using that macro. */\r
#define CONF_ENUM_DEF(valtype, keytype, keyword) CONF_ ## keyword,\r
enum config_primary_key { CONFIG_OPTIONS(CONF_ENUM_DEF) N_CONFIG_OPTIONS };\r
#undef CONF_ENUM_DEF\r
\r
/* Functions handling configuration structures. */\r
Conf *conf_new(void);                  /* create an empty configuration */\r
void conf_free(Conf *conf);\r
Conf *conf_copy(Conf *oldconf);\r
void conf_copy_into(Conf *dest, Conf *src);\r
/* Mandatory accessor functions: enforce by assertion that keys exist. */\r
bool conf_get_bool(Conf *conf, int key);\r
int conf_get_int(Conf *conf, int key);\r
int conf_get_int_int(Conf *conf, int key, int subkey);\r
char *conf_get_str(Conf *conf, int key);   /* result still owned by conf */\r
char *conf_get_str_str(Conf *conf, int key, const char *subkey);\r
Filename *conf_get_filename(Conf *conf, int key);\r
FontSpec *conf_get_fontspec(Conf *conf, int key); /* still owned by conf */\r
/* Optional accessor function: return NULL if key does not exist. */\r
char *conf_get_str_str_opt(Conf *conf, int key, const char *subkey);\r
/* Accessor function to step through a string-subkeyed list.\r
 * Returns the next subkey after the provided one, or the first if NULL.\r
 * Returns NULL if there are none left.\r
 * Both the return value and *subkeyout are still owned by conf. */\r
char *conf_get_str_strs(Conf *conf, int key, char *subkeyin, char **subkeyout);\r
/* Return the nth string subkey in a list. Owned by conf. NULL if beyond end */\r
char *conf_get_str_nthstrkey(Conf *conf, int key, int n);\r
/* Functions to set entries in configuration. Always copy their inputs. */\r
void conf_set_bool(Conf *conf, int key, bool value);\r
void conf_set_int(Conf *conf, int key, int value);\r
void conf_set_int_int(Conf *conf, int key, int subkey, int value);\r
void conf_set_str(Conf *conf, int key, const char *value);\r
void conf_set_str_str(Conf *conf, int key,\r
                      const char *subkey, const char *val);\r
void conf_del_str_str(Conf *conf, int key, const char *subkey);\r
void conf_set_filename(Conf *conf, int key, const Filename *val);\r
void conf_set_fontspec(Conf *conf, int key, const FontSpec *val);\r
/* Serialisation functions for Duplicate Session */\r
void conf_serialise(BinarySink *bs, Conf *conf);\r
bool conf_deserialise(Conf *conf, BinarySource *src);/*returns true on success*/\r
\r
/*\r
 * Functions to copy, free, serialise and deserialise FontSpecs.\r
 * Provided per-platform, to go with the platform's idea of a\r
 * FontSpec's contents.\r
 */\r
FontSpec *fontspec_copy(const FontSpec *f);\r
void fontspec_free(FontSpec *f);\r
void fontspec_serialise(BinarySink *bs, FontSpec *f);\r
FontSpec *fontspec_deserialise(BinarySource *src);\r
\r
/*\r
 * Exports from each platform's noise.c.\r
 */\r
typedef enum NoiseSourceId {\r
    NOISE_SOURCE_TIME,\r
    NOISE_SOURCE_IOID,\r
    NOISE_SOURCE_IOLEN,\r
    NOISE_SOURCE_KEY,\r
    NOISE_SOURCE_MOUSEBUTTON,\r
    NOISE_SOURCE_MOUSEPOS,\r
    NOISE_SOURCE_MEMINFO,\r
    NOISE_SOURCE_STAT,\r
    NOISE_SOURCE_RUSAGE,\r
    NOISE_SOURCE_FGWINDOW,\r
    NOISE_SOURCE_CAPTURE,\r
    NOISE_SOURCE_CLIPBOARD,\r
    NOISE_SOURCE_QUEUE,\r
    NOISE_SOURCE_CURSORPOS,\r
    NOISE_SOURCE_THREADTIME,\r
    NOISE_SOURCE_PROCTIME,\r
    NOISE_SOURCE_PERFCOUNT,\r
    NOISE_MAX_SOURCES\r
} NoiseSourceId;\r
void noise_get_heavy(void (*func) (void *, int));\r
void noise_get_light(void (*func) (void *, int));\r
void noise_regular(void);\r
void noise_ultralight(NoiseSourceId id, unsigned long data);\r
\r
/*\r
 * Exports from sshrand.c.\r
 */\r
void random_save_seed(void);\r
void random_destroy_seed(void);\r
\r
/*\r
 * Exports from settings.c.\r
 *\r
 * load_settings() and do_defaults() return false if the provided\r
 * session name didn't actually exist. But they still fill in the\r
 * provided Conf with _something_.\r
 */\r
const struct BackendVtable *backend_vt_from_name(const char *name);\r
const struct BackendVtable *backend_vt_from_proto(int proto);\r
char *get_remote_username(Conf *conf); /* dynamically allocated */\r
char *save_settings(const char *section, Conf *conf);\r
void save_open_settings(settings_w *sesskey, Conf *conf);\r
bool load_settings(const char *section, Conf *conf);\r
void load_open_settings(settings_r *sesskey, Conf *conf);\r
void get_sesslist(struct sesslist *, bool allocate);\r
bool do_defaults(const char *, Conf *);\r
void registry_cleanup(void);\r
void settings_set_default_protocol(int);\r
void settings_set_default_port(int);\r
\r
/*\r
 * Functions used by settings.c to provide platform-specific\r
 * default settings.\r
 *\r
 * (The integer one is expected to return `def' if it has no clear\r
 * opinion of its own. This is because there's no integer value\r
 * which I can reliably set aside to indicate `nil'. The string\r
 * function is perfectly all right returning NULL, of course. The\r
 * Filename and FontSpec functions are _not allowed_ to fail to\r
 * return, since these defaults _must_ be per-platform.)\r
 *\r
 * The 'Filename *' returned by platform_default_filename, and the\r
 * 'FontSpec *' returned by platform_default_fontspec, have ownership\r
 * transferred to the caller, and must be freed.\r
 */\r
char *platform_default_s(const char *name);\r
bool platform_default_b(const char *name, bool def);\r
int platform_default_i(const char *name, int def);\r
Filename *platform_default_filename(const char *name);\r
FontSpec *platform_default_fontspec(const char *name);\r
\r
/*\r
 * Exports from terminal.c.\r
 */\r
\r
Terminal *term_init(Conf *, struct unicode_data *, TermWin *);\r
void term_free(Terminal *);\r
void term_size(Terminal *, int, int, int);\r
void term_resize_request_completed(Terminal *);\r
void term_paint(Terminal *, int, int, int, int, bool);\r
void term_scroll(Terminal *, int, int);\r
void term_scroll_to_selection(Terminal *, int);\r
void term_pwron(Terminal *, bool);\r
void term_clrsb(Terminal *);\r
void term_mouse(Terminal *, Mouse_Button, Mouse_Button, Mouse_Action,\r
                int, int, bool, bool, bool);\r
void term_cancel_selection_drag(Terminal *);\r
void term_key(Terminal *, Key_Sym, wchar_t *, size_t, unsigned int,\r
              unsigned int);\r
void term_lost_clipboard_ownership(Terminal *, int clipboard);\r
void term_update(Terminal *);\r
void term_invalidate(Terminal *);\r
void term_blink(Terminal *, bool set_cursor);\r
void term_do_paste(Terminal *, const wchar_t *, int);\r
void term_nopaste(Terminal *);\r
void term_copyall(Terminal *, const int *, int);\r
void term_pre_reconfig(Terminal *, Conf *);\r
void term_reconfig(Terminal *, Conf *);\r
void term_request_copy(Terminal *, const int *clipboards, int n_clipboards);\r
void term_request_paste(Terminal *, int clipboard);\r
void term_seen_key_event(Terminal *);\r
size_t term_data(Terminal *, const void *data, size_t len);\r
void term_provide_backend(Terminal *term, Backend *backend);\r
void term_provide_logctx(Terminal *term, LogContext *logctx);\r
void term_set_focus(Terminal *term, bool has_focus);\r
char *term_get_ttymode(Terminal *term, const char *mode);\r
SeatPromptResult term_get_userpass_input(Terminal *term, prompts_t *p);\r
void term_set_trust_status(Terminal *term, bool trusted);\r
void term_keyinput(Terminal *, int codepage, const void *buf, int len);\r
void term_keyinputw(Terminal *, const wchar_t *widebuf, int len);\r
void term_get_cursor_position(Terminal *term, int *x, int *y);\r
void term_setup_window_titles(Terminal *term, const char *title_hostname);\r
void term_notify_minimised(Terminal *term, bool minimised);\r
void term_notify_palette_changed(Terminal *term);\r
void term_notify_window_pos(Terminal *term, int x, int y);\r
void term_notify_window_size_pixels(Terminal *term, int x, int y);\r
void term_palette_override(Terminal *term, unsigned osc4_index, rgb rgb);\r
\r
typedef enum SmallKeypadKey {\r
    SKK_HOME, SKK_END, SKK_INSERT, SKK_DELETE, SKK_PGUP, SKK_PGDN,\r
} SmallKeypadKey;\r
int format_arrow_key(char *buf, Terminal *term, int xkey,\r
                     bool shift, bool ctrl, bool alt, bool *consumed_alt);\r
int format_function_key(char *buf, Terminal *term, int key_number,\r
                        bool shift, bool ctrl, bool alt, bool *consumed_alt);\r
int format_small_keypad_key(char *buf, Terminal *term, SmallKeypadKey key,\r
                            bool shift, bool ctrl, bool alt,\r
                            bool *consumed_alt);\r
int format_numeric_keypad_key(char *buf, Terminal *term, char key,\r
                              bool shift, bool ctrl);\r
\r
/*\r
 * Exports from logging.c.\r
 */\r
struct LogPolicyVtable {\r
    /*\r
     * Pass Event Log entries on from LogContext to the front end,\r
     * which might write them to standard error or save them for a GUI\r
     * list box or other things.\r
     */\r
    void (*eventlog)(LogPolicy *lp, const char *event);\r
\r
    /*\r
     * Ask what to do about the specified output log file already\r
     * existing. Can return four values:\r
     *\r
     *  - 2 means overwrite the log file\r
     *  - 1 means append to the log file\r
     *  - 0 means cancel logging for this session\r
     *  - -1 means please wait, and callback() will be called with one\r
     *    of those options.\r
     */\r
    int (*askappend)(LogPolicy *lp, Filename *filename,\r
                     void (*callback)(void *ctx, int result), void *ctx);\r
\r
    /*\r
     * Emergency logging when the log file itself can't be opened,\r
     * which typically means we want to shout about it more loudly\r
     * than a mere Event Log entry.\r
     *\r
     * One reasonable option is to send it to the same place that\r
     * stderr output from the main session goes (so, either a console\r
     * tool's actual stderr, or a terminal window). In many cases this\r
     * is unlikely to cause this error message to turn up\r
     * embarrassingly in a log file of real server output, because the\r
     * whole point is that we haven't managed to open any such log\r
     * file :-)\r
     */\r
    void (*logging_error)(LogPolicy *lp, const char *event);\r
\r
    /*\r
     * Ask whether extra verbose log messages are required.\r
     */\r
    bool (*verbose)(LogPolicy *lp);\r
};\r
struct LogPolicy {\r
    const LogPolicyVtable *vt;\r
};\r
\r
static inline void lp_eventlog(LogPolicy *lp, const char *event)\r
{ lp->vt->eventlog(lp, event); }\r
static inline int lp_askappend(\r
    LogPolicy *lp, Filename *filename,\r
    void (*callback)(void *ctx, int result), void *ctx)\r
{ return lp->vt->askappend(lp, filename, callback, ctx); }\r
static inline void lp_logging_error(LogPolicy *lp, const char *event)\r
{ lp->vt->logging_error(lp, event); }\r
static inline bool lp_verbose(LogPolicy *lp)\r
{ return lp->vt->verbose(lp); }\r
\r
/* Defined in clicons.c, used in several console command-line tools */\r
extern LogPolicy console_cli_logpolicy[];\r
\r
int console_askappend(LogPolicy *lp, Filename *filename,\r
                      void (*callback)(void *ctx, int result), void *ctx);\r
void console_logging_error(LogPolicy *lp, const char *string);\r
void console_eventlog(LogPolicy *lp, const char *string);\r
bool null_lp_verbose_yes(LogPolicy *lp);\r
bool null_lp_verbose_no(LogPolicy *lp);\r
bool cmdline_lp_verbose(LogPolicy *lp);\r
\r
LogContext *log_init(LogPolicy *lp, Conf *conf);\r
void log_free(LogContext *logctx);\r
void log_reconfig(LogContext *logctx, Conf *conf);\r
void logfopen(LogContext *logctx);\r
void logfclose(LogContext *logctx);\r
void logtraffic(LogContext *logctx, unsigned char c, int logmode);\r
void logflush(LogContext *logctx);\r
LogPolicy *log_get_policy(LogContext *logctx);\r
void logevent(LogContext *logctx, const char *event);\r
void logeventf(LogContext *logctx, const char *fmt, ...) PRINTF_LIKE(2, 3);\r
void logeventvf(LogContext *logctx, const char *fmt, va_list ap);\r
\r
/*\r
 * Pass a dynamically allocated string to logevent and immediately\r
 * free it. Intended for use by wrapper macros which pass the return\r
 * value of dupprintf straight to this.\r
 */\r
void logevent_and_free(LogContext *logctx, char *event);\r
enum { PKT_INCOMING, PKT_OUTGOING };\r
enum { PKTLOG_EMIT, PKTLOG_BLANK, PKTLOG_OMIT };\r
struct logblank_t {\r
    int offset;\r
    int len;\r
    int type;\r
};\r
void log_packet(LogContext *logctx, int direction, int type,\r
                const char *texttype, const void *data, size_t len,\r
                int n_blanks, const struct logblank_t *blanks,\r
                const unsigned long *sequence,\r
                unsigned downstream_id, const char *additional_log_text);\r
\r
/*\r
 * Exports from testback.c\r
 */\r
\r
extern const struct BackendVtable null_backend;\r
extern const struct BackendVtable loop_backend;\r
\r
/*\r
 * Exports from raw.c.\r
 */\r
\r
extern const struct BackendVtable raw_backend;\r
\r
/*\r
 * Exports from rlogin.c.\r
 */\r
\r
extern const struct BackendVtable rlogin_backend;\r
\r
/*\r
 * Exports from telnet.c.\r
 */\r
\r
extern const struct BackendVtable telnet_backend;\r
\r
/*\r
 * Exports from ssh/ssh.c.\r
 */\r
extern const struct BackendVtable ssh_backend;\r
extern const struct BackendVtable sshconn_backend;\r
\r
/*\r
 * Exports from supdup.c.\r
 */\r
extern const struct BackendVtable supdup_backend;\r
\r
/*\r
 * Exports from ldisc.c.\r
 */\r
Ldisc *ldisc_create(Conf *, Terminal *, Backend *, Seat *);\r
void ldisc_configure(Ldisc *, Conf *);\r
void ldisc_free(Ldisc *);\r
void ldisc_send(Ldisc *, const void *buf, int len, bool interactive);\r
void ldisc_echoedit_update(Ldisc *);\r
typedef struct LdiscInputToken {\r
    /*\r
     * Structure that encodes any single item of data that Ldisc can\r
     * buffer: either a single character of raw data, or a session\r
     * special.\r
     */\r
    bool is_special;\r
    union {\r
        struct {\r
            /* if is_special == false */\r
            char chr;\r
        };\r
        struct {\r
            /* if is_special == true */\r
            SessionSpecialCode code;\r
            int arg;\r
        };\r
    };\r
} LdiscInputToken;\r
bool ldisc_has_input_buffered(Ldisc *);\r
LdiscInputToken ldisc_get_input_token(Ldisc *); /* asserts there is input */\r
void ldisc_enable_prompt_callback(Ldisc *, prompts_t *);\r
void ldisc_check_sendok(Ldisc *);\r
\r
/*\r
 * Exports from sshrand.c.\r
 */\r
\r
void random_add_noise(NoiseSourceId source, const void *noise, int length);\r
void random_read(void *buf, size_t size);\r
void random_get_savedata(void **data, int *len);\r
extern int random_active;\r
/* The random number subsystem is activated if at least one other entity\r
 * within the program expresses an interest in it. So each SSH session\r
 * calls random_ref on startup and random_unref on shutdown. */\r
void random_ref(void);\r
void random_unref(void);\r
/* random_clear is equivalent to calling random_unref as many times as\r
 * necessary to shut down the global PRNG instance completely. It's\r
 * not needed in normal applications, but the command-line PuTTYgen\r
 * test finds it useful to clean up after each invocation of the\r
 * logical main() no matter whether it needed random numbers or\r
 * not. */\r
void random_clear(void);\r
/* random_setup_custom sets up the process-global random number\r
 * generator specially, with a hash function of your choice. */\r
void random_setup_custom(const ssh_hashalg *hash);\r
/* random_setup_special() is a macro wrapper on that, which makes an\r
 * extra-big one based on the largest hash function we have. It's\r
 * defined this way to avoid what would otherwise be an unnecessary\r
 * module dependency from sshrand.c to a hash function implementation. */\r
#define random_setup_special() random_setup_custom(&ssh_shake256_114bytes)\r
/* Manually drop a random seed into the random number generator, e.g.\r
 * just before generating a key. */\r
void random_reseed(ptrlen seed);\r
/* Limit on how much entropy is worth putting into the generator (bits). */\r
size_t random_seed_bits(void);\r
\r
/*\r
 * Exports from pinger.c.\r
 */\r
typedef struct Pinger Pinger;\r
Pinger *pinger_new(Conf *conf, Backend *backend);\r
void pinger_reconfig(Pinger *, Conf *oldconf, Conf *newconf);\r
void pinger_free(Pinger *);\r
\r
/*\r
 * Exports from modules in utils.\r
 */\r
\r
#include "misc.h"\r
bool conf_launchable(Conf *conf);\r
char const *conf_dest(Conf *conf);\r
\r
/*\r
 * Exports from sessprep.c.\r
 */\r
void prepare_session(Conf *conf);\r
\r
/*\r
 * Exports from version.c and cmake_commit.c.\r
 */\r
extern const char ver[];\r
extern const char commitid[];\r
\r
/*\r
 * Exports from unicode.c in platform subdirs.\r
 */\r
#ifndef CP_UTF8\r
#define CP_UTF8 65001\r
#endif\r
/* void init_ucs(void); -- this is now in platform-specific headers */\r
bool is_dbcs_leadbyte(int codepage, char byte);\r
int mb_to_wc(int codepage, int flags, const char *mbstr, int mblen,\r
             wchar_t *wcstr, int wclen);\r
int wc_to_mb(int codepage, int flags, const wchar_t *wcstr, int wclen,\r
             char *mbstr, int mblen, const char *defchr);\r
wchar_t xlat_uskbd2cyrllic(int ch);\r
int check_compose(int first, int second);\r
int decode_codepage(const char *cp_name);\r
const char *cp_enumerate (int index);\r
const char *cp_name(int codepage);\r
void get_unitab(int codepage, wchar_t *unitab, int ftype);\r
\r
/*\r
 * Exports from wcwidth.c\r
 */\r
int mk_wcwidth(unsigned int ucs);\r
int mk_wcswidth(const unsigned int *pwcs, size_t n);\r
int mk_wcwidth_cjk(unsigned int ucs);\r
int mk_wcswidth_cjk(const unsigned int *pwcs, size_t n);\r
\r
/*\r
 * Exports from agent-client.c in platform subdirs.\r
 *\r
 * agent_query returns NULL for here's-a-response, and non-NULL for\r
 * query-in- progress. In the latter case there will be a call to\r
 * `callback' at some future point, passing callback_ctx as the first\r
 * parameter and the actual reply data as the second and third.\r
 *\r
 * The response may be a NULL pointer (in either of the synchronous\r
 * or asynchronous cases), which indicates failure to receive a\r
 * response.\r
 *\r
 * When the return from agent_query is not NULL, it identifies the\r
 * in-progress query in case it needs to be cancelled. If\r
 * agent_cancel_query is called, then the pending query is destroyed\r
 * and the callback will not be called. (E.g. if you're going to throw\r
 * away the thing you were using as callback_ctx.)\r
 *\r
 * Passing a null pointer as callback forces agent_query to behave\r
 * synchronously, i.e. it will block if necessary, and guarantee to\r
 * return NULL. The wrapper function agent_query_synchronous()\r
 * (defined in its own module aqsync.c) makes this easier.\r
 */\r
typedef struct agent_pending_query agent_pending_query;\r
agent_pending_query *agent_query(\r
    strbuf *in, void **out, int *outlen,\r
    void (*callback)(void *, void *, int), void *callback_ctx);\r
void agent_cancel_query(agent_pending_query *);\r
void agent_query_synchronous(strbuf *in, void **out, int *outlen);\r
bool agent_exists(void);\r
\r
/* For stream-oriented agent connections, if available. */\r
Socket *agent_connect(Plug *plug);\r
\r
/*\r
 * Exports from wildcard.c\r
 */\r
const char *wc_error(int value);\r
int wc_match_pl(const char *wildcard, ptrlen target);\r
int wc_match(const char *wildcard, const char *target);\r
bool wc_unescape(char *output, const char *wildcard);\r
\r
/*\r
 * Exports from frontend (dialog.c etc)\r
 */\r
void pgp_fingerprints(void);\r
/*\r
 * have_ssh_host_key() just returns true if a key of that type is\r
 * already cached and false otherwise.\r
 */\r
bool have_ssh_host_key(const char *host, int port, const char *keytype);\r
\r
/*\r
 * Exports from console frontends (console.c in platform subdirs)\r
 * that aren't equivalents to things in windlg.c et al.\r
 */\r
extern bool console_batch_mode, console_antispoof_prompt;\r
SeatPromptResult console_get_userpass_input(prompts_t *p);\r
bool is_interactive(void);\r
void console_print_error_msg(const char *prefix, const char *msg);\r
void console_print_error_msg_fmt_v(\r
    const char *prefix, const char *fmt, va_list ap);\r
void console_print_error_msg_fmt(const char *prefix, const char *fmt, ...)\r
    PRINTF_LIKE(2, 3);\r
\r
/*\r
 * Exports from printing.c in platform subdirs.\r
 */\r
typedef struct printer_enum_tag printer_enum;\r
typedef struct printer_job_tag printer_job;\r
printer_enum *printer_start_enum(int *nprinters);\r
char *printer_get_name(printer_enum *, int);\r
void printer_finish_enum(printer_enum *);\r
printer_job *printer_start_job(char *printer);\r
void printer_job_data(printer_job *, const void *, size_t);\r
void printer_finish_job(printer_job *);\r
\r
/*\r
 * Exports from cmdline.c (and also cmdline_error(), which is\r
 * defined differently in various places and required _by_\r
 * cmdline.c).\r
 *\r
 * Note that cmdline_process_param takes a const option string, but a\r
 * writable argument string. That's not a mistake - that's so it can\r
 * zero out password arguments in the hope of not having them show up\r
 * avoidably in Unix 'ps'.\r
 */\r
struct cmdline_get_passwd_input_state { bool tried; };\r
#define CMDLINE_GET_PASSWD_INPUT_STATE_INIT { .tried = false }\r
extern const cmdline_get_passwd_input_state cmdline_get_passwd_input_state_new;\r
\r
int cmdline_process_param(const char *, char *, int, Conf *);\r
void cmdline_run_saved(Conf *);\r
void cmdline_cleanup(void);\r
SeatPromptResult cmdline_get_passwd_input(\r
    prompts_t *p, cmdline_get_passwd_input_state *state, bool restartable);\r
bool cmdline_host_ok(Conf *);\r
bool cmdline_verbose(void);\r
bool cmdline_loaded_session(void);\r
\r
/*\r
 * Here we have a flags word provided by each tool, which describes\r
 * the capabilities of that tool that cmdline.c needs to know about.\r
 * It will refuse certain command-line options if a particular tool\r
 * inherently can't do anything sensible. For example, the file\r
 * transfer tools (psftp, pscp) can't do a great deal with protocol\r
 * selections (ever tried running scp over telnet?) or with port\r
 * forwarding (even if it wasn't a hideously bad idea, they don't have\r
 * the select/poll infrastructure to make them work).\r
 */\r
extern const unsigned cmdline_tooltype;\r
\r
/* Bit flags for the above */\r
#define TOOLTYPE_LIST(X)                        \\r
    X(TOOLTYPE_FILETRANSFER)                    \\r
    X(TOOLTYPE_NONNETWORK)                      \\r
    X(TOOLTYPE_HOST_ARG)                        \\r
    X(TOOLTYPE_HOST_ARG_CAN_BE_SESSION)         \\r
    X(TOOLTYPE_HOST_ARG_PROTOCOL_PREFIX)        \\r
    X(TOOLTYPE_HOST_ARG_FROM_LAUNCHABLE_LOAD)   \\r
    X(TOOLTYPE_PORT_ARG)                        \\r
    X(TOOLTYPE_NO_VERBOSE_OPTION)               \\r
    /* end of list */\r
#define BITFLAG_INDEX(val) val ## _bitflag_index,\r
enum { TOOLTYPE_LIST(BITFLAG_INDEX) };\r
#define BITFLAG_DEF(val) val = 1U << (val ## _bitflag_index),\r
enum { TOOLTYPE_LIST(BITFLAG_DEF) };\r
\r
void cmdline_error(const char *, ...) PRINTF_LIKE(1, 2);\r
\r
/*\r
 * Exports from config.c.\r
 */\r
struct controlbox;\r
void conf_radiobutton_handler(dlgcontrol *ctrl, dlgparam *dlg,\r
                              void *data, int event);\r
#define CHECKBOX_INVERT (1<<30)\r
void conf_checkbox_handler(dlgcontrol *ctrl, dlgparam *dlg,\r
                           void *data, int event);\r
void conf_editbox_handler(dlgcontrol *ctrl, dlgparam *dlg,\r
                          void *data, int event);\r
void conf_filesel_handler(dlgcontrol *ctrl, dlgparam *dlg,\r
                          void *data, int event);\r
void conf_fontsel_handler(dlgcontrol *ctrl, dlgparam *dlg,\r
                          void *data, int event);\r
\r
struct conf_editbox_handler_type {\r
    /* Structure passed as context2 to conf_editbox_handler */\r
    enum { EDIT_STR, EDIT_INT, EDIT_FIXEDPOINT } type;\r
    union {\r
        /*\r
         * EDIT_STR means the edit box is connected to a string\r
         * field in Conf. No further parameters needed.\r
         */\r
\r
        /*\r
         * EDIT_INT means the edit box is connected to an int field in\r
         * Conf, and the input string is interpreted as decimal. No\r
         * further parameters needed. (But we could add one here later\r
         * if for some reason we wanted int fields in hex.)\r
         */\r
\r
        /*\r
         * EDIT_FIXEDPOINT means the edit box is connected to an int\r
         * field in Conf, but the input string is interpreted as\r
         * _floating point_, and converted to/from the output int by\r
         * means of a fixed denominator. That is,\r
         *\r
         *   (floating value in edit box) * denominator = value in Conf\r
         */\r
        struct {\r
            double denominator;\r
        };\r
    };\r
};\r
\r
extern const struct conf_editbox_handler_type conf_editbox_str;\r
extern const struct conf_editbox_handler_type conf_editbox_int;\r
#define ED_STR CP(&conf_editbox_str)\r
#define ED_INT CP(&conf_editbox_int)\r
\r
void setup_config_box(struct controlbox *b, bool midsession,\r
                      int protocol, int protcfginfo);\r
\r
void setup_ca_config_box(struct controlbox *b);\r
\r
/* Platforms provide this to be called from config.c */\r
void show_ca_config_box(dlgparam *dlg);\r
extern const bool has_ca_config_box; /* false if, e.g., we're PuTTYtel */\r
\r
/* Visible outside config.c so that platforms can use it to recognise\r
 * the proxy type control */\r
void proxy_type_handler(dlgcontrol *ctrl, dlgparam *dlg,\r
                        void *data, int event);\r
/* And then they'll set this flag in its generic.context.i */\r
#define PROXY_UI_FLAG_LOCAL 1 /* has a local proxy */\r
\r
/*\r
 * Exports from bidi.c.\r
 */\r
#define BIDI_CHAR_INDEX_NONE ((unsigned short)-1)\r
typedef struct bidi_char {\r
    unsigned int origwc, wc;\r
    unsigned short index, nchars;\r
} bidi_char;\r
BidiContext *bidi_new_context(void);\r
void bidi_free_context(BidiContext *ctx);\r
void do_bidi(BidiContext *ctx, bidi_char *line, size_t count);\r
int do_shape(bidi_char *line, bidi_char *to, int count);\r
bool is_rtl(int c);\r
\r
/*\r
 * X11 auth mechanisms we know about.\r
 */\r
enum {\r
    X11_NO_AUTH,\r
    X11_MIT,                           /* MIT-MAGIC-COOKIE-1 */\r
    X11_XDM,                           /* XDM-AUTHORIZATION-1 */\r
    X11_NAUTHS\r
};\r
extern const char *const x11_authnames[X11_NAUTHS];\r
\r
/*\r
 * An enum for the copy-paste UI action configuration.\r
 */\r
enum {\r
    CLIPUI_NONE,     /* UI action has no copy/paste effect */\r
    CLIPUI_IMPLICIT, /* use the default clipboard implicit in mouse actions  */\r
    CLIPUI_EXPLICIT, /* use the default clipboard for explicit Copy/Paste */\r
    CLIPUI_CUSTOM,   /* use a named clipboard (on systems that support it) */\r
};\r
\r
/*\r
 * Miscellaneous exports from the platform-specific code.\r
 *\r
 * filename_serialise and filename_deserialise have the same semantics\r
 * as fontspec_serialise and fontspec_deserialise above.\r
 */\r
Filename *filename_from_str(const char *string);\r
const char *filename_to_str(const Filename *fn);\r
bool filename_equal(const Filename *f1, const Filename *f2);\r
bool filename_is_null(const Filename *fn);\r
Filename *filename_copy(const Filename *fn);\r
void filename_free(Filename *fn);\r
void filename_serialise(BinarySink *bs, const Filename *f);\r
Filename *filename_deserialise(BinarySource *src);\r
char *get_username(void);              /* return value needs freeing */\r
char *get_random_data(int bytes, const char *device); /* used in cmdgen.c */\r
char filename_char_sanitise(char c);   /* rewrite special pathname chars */\r
bool open_for_write_would_lose_data(const Filename *fn);\r
\r
/*\r
 * Exports and imports from timing.c.\r
 *\r
 * schedule_timer() asks the front end to schedule a callback to a\r
 * timer function in a given number of ticks. The returned value is\r
 * the time (in ticks since an arbitrary offset) at which the\r
 * callback can be expected. This value will also be passed as the\r
 * `now' parameter to the callback function. Hence, you can (for\r
 * example) schedule an event at a particular time by calling\r
 * schedule_timer() and storing the return value in your context\r
 * structure as the time when that event is due. The first time a\r
 * callback function gives you that value or more as `now', you do\r
 * the thing.\r
 *\r
 * expire_timer_context() drops all current timers associated with\r
 * a given value of ctx (for when you're about to free ctx).\r
 *\r
 * run_timers() is called from the front end when it has reason to\r
 * think some timers have reached their moment, or when it simply\r
 * needs to know how long to wait next. We pass it the time we\r
 * think it is. It returns true and places the time when the next\r
 * timer needs to go off in `next', or alternatively it returns\r
 * false if there are no timers at all pending.\r
 *\r
 * timer_change_notify() must be supplied by the front end; it\r
 * notifies the front end that a new timer has been added to the\r
 * list which is sooner than any existing ones. It provides the\r
 * time when that timer needs to go off.\r
 *\r
 * *** FRONT END IMPLEMENTORS NOTE:\r
 *\r
 * There's an important subtlety in the front-end implementation of\r
 * the timer interface. When a front end is given a `next' value,\r
 * either returned from run_timers() or via timer_change_notify(),\r
 * it should ensure that it really passes _that value_ as the `now'\r
 * parameter to its next run_timers call. It should _not_ simply\r
 * call GETTICKCOUNT() to get the `now' parameter when invoking\r
 * run_timers().\r
 *\r
 * The reason for this is that an OS's system clock might not agree\r
 * exactly with the timing mechanisms it supplies to wait for a\r
 * given interval. I'll illustrate this by the simple example of\r
 * Unix Plink, which uses timeouts to poll() in a way which for\r
 * these purposes can simply be considered to be a wait() function.\r
 * Suppose, for the sake of argument, that this wait() function\r
 * tends to return early by 1%. Then a possible sequence of actions\r
 * is:\r
 *\r
 *  - run_timers() tells the front end that the next timer firing\r
 *    is 10000ms from now.\r
 *  - Front end calls wait(10000ms), but according to\r
 *    GETTICKCOUNT() it has only waited for 9900ms.\r
 *  - Front end calls run_timers() again, passing time T-100ms as\r
 *    `now'.\r
 *  - run_timers() does nothing, and says the next timer firing is\r
 *    still 100ms from now.\r
 *  - Front end calls wait(100ms), which only waits for 99ms.\r
 *  - Front end calls run_timers() yet again, passing time T-1ms.\r
 *  - run_timers() says there's still 1ms to wait.\r
 *  - Front end calls wait(1ms).\r
 *\r
 * If you're _lucky_ at this point, wait(1ms) will actually wait\r
 * for 1ms and you'll only have woken the program up three times.\r
 * If you're unlucky, wait(1ms) might do nothing at all due to\r
 * being below some minimum threshold, and you might find your\r
 * program spends the whole of the last millisecond tight-looping\r
 * between wait() and run_timers().\r
 *\r
 * Instead, what you should do is to _save_ the precise `next'\r
 * value provided by run_timers() or via timer_change_notify(), and\r
 * use that precise value as the input to the next run_timers()\r
 * call. So:\r
 *\r
 *  - run_timers() tells the front end that the next timer firing\r
 *    is at time T, 10000ms from now.\r
 *  - Front end calls wait(10000ms).\r
 *  - Front end then immediately calls run_timers() and passes it\r
 *    time T, without stopping to check GETTICKCOUNT() at all.\r
 *\r
 * This guarantees that the program wakes up only as many times as\r
 * there are actual timer actions to be taken, and that the timing\r
 * mechanism will never send it into a tight loop.\r
 *\r
 * (It does also mean that the timer action in the above example\r
 * will occur 100ms early, but this is not generally critical. And\r
 * the hypothetical 1% error in wait() will be partially corrected\r
 * for anyway when, _after_ run_timers() returns, you call\r
 * GETTICKCOUNT() and compare the result with the returned `next'\r
 * value to find out how long you have to make your next wait().)\r
 */\r
typedef void (*timer_fn_t)(void *ctx, unsigned long now);\r
unsigned long schedule_timer(int ticks, timer_fn_t fn, void *ctx);\r
void expire_timer_context(void *ctx);\r
bool run_timers(unsigned long now, unsigned long *next);\r
void timer_change_notify(unsigned long next);\r
unsigned long timing_last_clock(void);\r
\r
/*\r
 * Exports from callback.c.\r
 *\r
 * This provides a method of queuing function calls to be run at the\r
 * earliest convenience from the top-level event loop. Use it if\r
 * you're deep in a nested chain of calls and want to trigger an\r
 * action which will probably lead to your function being re-entered\r
 * recursively if you just call the initiating function the normal\r
 * way.\r
 *\r
 * Most front ends run the queued callbacks by simply calling\r
 * run_toplevel_callbacks() after handling each event in their\r
 * top-level event loop. However, if a front end doesn't have control\r
 * over its own event loop (e.g. because it's using GTK) then it can\r
 * instead request notifications when a callback is available, so that\r
 * it knows to ask its delegate event loop to do the same thing. Also,\r
 * if a front end needs to know whether a callback is pending without\r
 * actually running it (e.g. so as to put a zero timeout on a poll()\r
 * call) then it can call toplevel_callback_pending(), which will\r
 * return true if at least one callback is in the queue.\r
 *\r
 * run_toplevel_callbacks() returns true if it ran any actual code.\r
 * This can be used as a means of speculatively terminating a poll\r
 * loop, as in PSFTP, for example - if a callback has run then perhaps\r
 * it might have done whatever the loop's caller was waiting for.\r
 */\r
void queue_toplevel_callback(toplevel_callback_fn_t fn, void *ctx);\r
bool run_toplevel_callbacks(void);\r
bool toplevel_callback_pending(void);\r
void delete_callbacks_for_context(void *ctx);\r
\r
/*\r
 * Another facility in callback.c deals with 'idempotent' callbacks,\r
 * defined as those which never need to be scheduled again if they are\r
 * already scheduled and have not yet run. (An example would be one\r
 * which, when called, empties a queue of data completely: when data\r
 * is added to the queue, you must ensure a run of the queue-consuming\r
 * function has been scheduled, but if one is already pending, you\r
 * don't need to schedule a second one.)\r
 */\r
struct IdempotentCallback {\r
    toplevel_callback_fn_t fn;\r
    void *ctx;\r
    bool queued;\r
};\r
void queue_idempotent_callback(struct IdempotentCallback *ic);\r
\r
typedef void (*toplevel_callback_notify_fn_t)(void *ctx);\r
void request_callback_notifications(toplevel_callback_notify_fn_t notify,\r
                                    void *ctx);\r
\r
/*\r
 * Facility provided by the platform to spawn a parallel subprocess\r
 * and present its stdio via a Socket.\r
 *\r
 * 'prefix' indicates the prefix that should appear on messages passed\r
 * to plug_log to provide stderr output from the process.\r
 */\r
Socket *platform_start_subprocess(const char *cmd, Plug *plug,\r
                                  const char *prefix);\r
\r
/*\r
 * Define no-op macros for the jump list functions, on platforms that\r
 * don't support them. (This is a bit of a hack, and it'd be nicer to\r
 * localise even the calls to those functions into the Windows front\r
 * end, but it'll do for the moment.)\r
 */\r
#ifndef JUMPLIST_SUPPORTED\r
#define add_session_to_jumplist(x) ((void)0)\r
#define remove_session_from_jumplist(x) ((void)0)\r
#endif\r
\r
/* SURROGATE PAIR */\r
#ifndef HIGH_SURROGATE_START /* in some toolchains <winnls.h> defines these */\r
#define HIGH_SURROGATE_START 0xd800\r
#define HIGH_SURROGATE_END 0xdbff\r
#define LOW_SURROGATE_START 0xdc00\r
#define LOW_SURROGATE_END 0xdfff\r
#endif\r
\r
/* These macros exist in the Windows API, so the environment may\r
 * provide them. If not, define them in terms of the above. */\r
#ifndef IS_HIGH_SURROGATE\r
#define IS_HIGH_SURROGATE(wch) (((wch) >= HIGH_SURROGATE_START) && \\r
                                ((wch) <= HIGH_SURROGATE_END))\r
#define IS_LOW_SURROGATE(wch) (((wch) >= LOW_SURROGATE_START) && \\r
                               ((wch) <= LOW_SURROGATE_END))\r
#define IS_SURROGATE_PAIR(hs, ls) (IS_HIGH_SURROGATE(hs) && \\r
                                   IS_LOW_SURROGATE(ls))\r
#endif\r
\r
\r
#define IS_SURROGATE(wch) (((wch) >= HIGH_SURROGATE_START) &&   \\r
                           ((wch) <= LOW_SURROGATE_END))\r
#define HIGH_SURROGATE_OF(codept) \\r
    (HIGH_SURROGATE_START + (((codept) - 0x10000) >> 10))\r
#define LOW_SURROGATE_OF(codept) \\r
    (LOW_SURROGATE_START + (((codept) - 0x10000) & 0x3FF))\r
#define FROM_SURROGATES(wch1, wch2) \\r
    (0x10000 + (((wch1) & 0x3FF) << 10) + ((wch2) & 0x3FF))\r
\r
#endif\r