Richer data type for interactive prompt results.

All the seat functions that request an interactive prompt of some kind
to the user - both the main seat_get_userpass_input and the various
confirmation dialogs for things like host keys - were using a simple
int return value, with the general semantics of 0 = "fail", 1 =
"proceed" (and in the case of seat_get_userpass_input, answers to the
prompts were provided), and -1 = "request in progress, wait for a
callback".

In this commit I change all those functions' return types to a new
struct called SeatPromptResult, whose primary field is an enum
replacing those simple integer values.

The main purpose is that the enum has not three but _four_ values: the
"fail" result has been split into 'user abort' and 'software abort'.
The distinction is that a user abort occurs as a result of an
interactive UI action, such as the user clicking 'cancel' in a dialog
box or hitting ^D or ^C at a terminal password prompt - and therefore,
there's no need to display an error message telling the user that the
interactive operation has failed, because the user already knows,
because they _did_ it. 'Software abort' is from any other cause, where
PuTTY is the first to know there was a problem, and has to tell the
user.

We already had this 'user abort' vs 'software abort' distinction in
other parts of the code - the SSH backend has separate termination
functions which protocol layers can call. But we assumed that any
failure from an interactive prompt request fell into the 'user abort'
category, which is not true. A couple of examples: if you configure a
host key fingerprint in your saved session via the SSH > Host keys
pane, and the server presents a host key that doesn't match it, then
verify_ssh_host_key would report that the user had aborted the
connection, and feel no need to tell the user what had gone wrong!
Similarly, if a password provided on the command line was not
accepted, then (after I fixed the semantics of that in the previous
commit) the same wrong handling would occur.

So now, those Seat prompt functions too can communicate whether the
user or the software originated a connection abort. And in the latter
case, we also provide an error message to present to the user. Result:
in those two example cases (and others), error messages should no
longer go missing.

Implementation note: to avoid the hassle of having the error message
in a SeatPromptResult being a dynamically allocated string (and hence,
every recipient of one must always check whether it's non-NULL and
free it on every exit path, plus being careful about copying the
struct around), I've instead arranged that the structure contains a
function pointer and a couple of parameters, so that the string form
of the message can be constructed on demand. That way, the only users
who need to free it are the ones who actually _asked_ for it in the
first place, which is a much smaller set.

(This is one of the rare occasions that I regret not having C++'s
extra features available in this code base - a unique_ptr or
shared_ptr to a string would have been just the thing here, and the
compiler would have done all the hard work for me of remembering where
to insert the frees!)

utils/CMakeLists.txt

@@ -26,6 +26,7 @@ add_sources_from_current_dir(utils
   host_strduptrim.c
   host_strrchr.c
   log_proxy_stderr.c
+  make_spr_sw_abort_static.c
   marshal.c
   memory.c
   memxor.c
@@ -42,6 +43,7 @@ add_sources_from_current_dir(utils
   sk_free_peer_info.c
   smemclr.c
   smemeq.c
+  spr_get_error_message.c
   ssh2_pick_fingerprint.c
   sshutils.c
   strbuf.c

utils/make_spr_sw_abort_static.c

@@ -0,0 +1,21 @@
+/*
+ * Constructor function for a SeatPromptResult of the 'software abort'
+ * category, whose error message is in the simplest possible form of a
+ * static string constant.
+ */
+
+#include "putty.h"
+
+static void spr_static_errfn(SeatPromptResult spr, BinarySink *bs)
+{
+    put_dataz(bs, spr.errdata_lit);
+}
+
+SeatPromptResult make_spr_sw_abort_static(const char *str)
+{
+    SeatPromptResult spr;
+    spr.kind = SPRK_SW_ABORT;
+    spr.errfn = spr_static_errfn;
+    spr.errdata_lit = str;
+    return spr;
+}

utils/nullseat.c

@@ -11,7 +11,8 @@ void nullseat_sent(Seat *seat, size_t bufsize) {}
 size_t nullseat_banner(Seat *seat, const void *data, size_t len) {return 0;}
 size_t nullseat_banner_to_stderr(Seat *seat, const void *data, size_t len)
 { return seat_output(seat, SEAT_OUTPUT_STDERR, data, len); }
-int nullseat_get_userpass_input(Seat *seat, prompts_t *p) { return 0; }
+SeatPromptResult nullseat_get_userpass_input(Seat *seat, prompts_t *p)
+{ return SPR_SW_ABORT("this seat can't handle interactive prompts"); }
 void nullseat_notify_session_started(Seat *seat) {}
 void nullseat_notify_remote_exit(Seat *seat) {}
 void nullseat_notify_remote_disconnect(Seat *seat) {}
@@ -19,16 +20,19 @@ void nullseat_connection_fatal(Seat *seat, const char *message) {}
 void nullseat_update_specials_menu(Seat *seat) {}
 char *nullseat_get_ttymode(Seat *seat, const char *mode) { return NULL; }
 void nullseat_set_busy_status(Seat *seat, BusyStatus status) {}
-int nullseat_confirm_ssh_host_key(
+SeatPromptResult nullseat_confirm_ssh_host_key(
     Seat *seat, const char *host, int port, const char *keytype,
     char *keystr, const char *keydisp, char **key_fingerprints, bool mismatch,
-    void (*callback)(void *ctx, int result), void *ctx) { return 0; }
-int nullseat_confirm_weak_crypto_primitive(
+    void (*callback)(void *ctx, SeatPromptResult result), void *ctx)
+{ return SPR_SW_ABORT("this seat can't handle interactive prompts"); }
+SeatPromptResult nullseat_confirm_weak_crypto_primitive(
     Seat *seat, const char *algtype, const char *algname,
-    void (*callback)(void *ctx, int result), void *ctx) { return 0; }
-int nullseat_confirm_weak_cached_hostkey(
+    void (*callback)(void *ctx, SeatPromptResult result), void *ctx)
+{ return SPR_SW_ABORT("this seat can't handle interactive prompts"); }
+SeatPromptResult nullseat_confirm_weak_cached_hostkey(
     Seat *seat, const char *algname, const char *betteralgs,
-    void (*callback)(void *ctx, int result), void *ctx) { return 0; }
+    void (*callback)(void *ctx, SeatPromptResult result), void *ctx)
+{ return SPR_SW_ABORT("this seat can't handle interactive prompts"); }
 bool nullseat_is_never_utf8(Seat *seat) { return false; }
 bool nullseat_is_always_utf8(Seat *seat) { return true; }
 void nullseat_echoedit_update(Seat *seat, bool echoing, bool editing) {}

utils/prompts.c

@@ -11,7 +11,7 @@ prompts_t *new_prompts(void)
     p->prompts = NULL;
     p->n_prompts = p->prompts_size = 0;
     p->data = NULL;
-    p->idata = -1;
+    p->spr = SPR_INCOMPLETE;
     p->to_server = true; /* to be on the safe side */
     p->name = p->instruction = NULL;
     p->name_reqd = p->instr_reqd = false;

utils/spr_get_error_message.c

@@ -0,0 +1,13 @@
+/*
+ * Construct the error message from a SeatPromptResult, and return it
+ * in a dynamically allocated string.
+ */
+
+#include "putty.h"
+
+char *spr_get_error_message(SeatPromptResult spr)
+{
+    strbuf *sb = strbuf_new();
+    spr.errfn(spr, BinarySink_UPCAST(sb));
+    return strbuf_to_str(sb);
+}

utils/tempseat.c

@@ -218,7 +218,7 @@ static bool tempseat_has_mixed_input_stream(Seat *seat)
  * for the network connection.
  */
 
-static int tempseat_get_userpass_input(Seat *seat, prompts_t *p)
+static SeatPromptResult tempseat_get_userpass_input(Seat *seat, prompts_t *p)
 {
     /*
      * Interactive prompts of this nature are a thing that a backend
@@ -235,25 +235,25 @@ static size_t tempseat_banner(Seat *seat, const void *data, size_t len)
     unreachable("banner should never be called on TempSeat");
 }
 
-static int tempseat_confirm_ssh_host_key(
+static SeatPromptResult tempseat_confirm_ssh_host_key(
     Seat *seat, const char *host, int port, const char *keytype,
     char *keystr, const char *keydisp, char **key_fingerprints, bool mismatch,
-    void (*callback)(void *ctx, int result), void *ctx)
+    void (*callback)(void *ctx, SeatPromptResult result), void *ctx)
 {
     unreachable("confirm_ssh_host_key should never be called on TempSeat");
 }
 
-static int tempseat_confirm_weak_crypto_primitive(
+static SeatPromptResult tempseat_confirm_weak_crypto_primitive(
     Seat *seat, const char *algtype, const char *algname,
-    void (*callback)(void *ctx, int result), void *ctx)
+    void (*callback)(void *ctx, SeatPromptResult result), void *ctx)
 {
     unreachable("confirm_weak_crypto_primitive "
                 "should never be called on TempSeat");
 }
 
-static int tempseat_confirm_weak_cached_hostkey(
+static SeatPromptResult tempseat_confirm_weak_cached_hostkey(
     Seat *seat, const char *algname, const char *betteralgs,
-    void (*callback)(void *ctx, int result), void *ctx)
+    void (*callback)(void *ctx, SeatPromptResult result), void *ctx)
 {
     unreachable("confirm_weak_cached_hostkey "
                 "should never be called on TempSeat");