The Windows host key dialogs now have a `Help' button that should give

appropriate context help, iff the help file is present. (Shame it's prey to
`winhelp-crash'.)

(I've perpetrated a widening of visibility of `hwnd'; the alternative, putting
it into a frontend handle, seemed too likely to cause maintenance trouble if
we don't also _use_ that frontend handle everywhere we now use the global
`hwnd'.)

[originally from svn r5309]

doc/errors.but

@@ -15,6 +15,8 @@ bug (see \k{feedback}) and we will add documentation for it.
 \H{errors-hostkey-absent} \q{The server's host key is not cached in
 the registry}
 
+\cfg{winhelp-topic}{errors.hostkey.absent}
+
 This error message occurs when PuTTY connects to a new SSH server.
 Every server identifies itself by means of a host key; once PuTTY
 knows the host key for a server, it will be able to detect if a
@@ -36,6 +38,8 @@ See \k{gs-hostkey} for more information on host keys.
 
 \H{errors-hostkey-wrong} \q{WARNING - POTENTIAL SECURITY BREACH!}
 
+\cfg{winhelp-topic}{errors.hostkey.changed}
+
 This message, followed by \q{The server's host key does not match
 the one PuTTY has cached in the registry}, means that PuTTY has
 connected to the SSH server before, knows what its host key

windows/windlg.c

@@ -701,6 +701,28 @@ void showabout(HWND hwnd)
     DialogBox(hinst, MAKEINTRESOURCE(IDD_ABOUTBOX), hwnd, AboutProc);
 }
 
+/* Helper function for verify_ssh_host_key(). */
+static VOID CALLBACK verify_ssh_host_key_help(LPHELPINFO lpHelpInfo)
+{
+    if (help_path) {
+	char *context = NULL;
+#define CHECK_CTX(name) \
+	do { \
+	    if (lpHelpInfo->dwContextId == WINHELP_CTXID_ ## name) \
+		context = WINHELP_CTX_ ## name; \
+	} while (0)
+	CHECK_CTX(errors_hostkey_absent);
+	CHECK_CTX(errors_hostkey_changed);
+#undef CHECK_CTX
+	if (context) {
+	    char *cmd = dupprintf("JI(`',`%s')", context);
+	    WinHelp(hwnd, help_path, HELP_COMMAND, (DWORD)cmd);
+	    sfree(cmd);
+	    requested_help = TRUE;
+	}
+    }
+}
+
 void verify_ssh_host_key(void *frontend, char *host, int port, char *keytype,
 			 char *keystr, char *fingerprint)
 {
@@ -738,6 +760,22 @@ void verify_ssh_host_key(void *frontend, char *host, int port, char *keytype,
 
     static const char mbtitle[] = "%s Security Alert";
 
+    UINT help_button = 0;
+    MSGBOXPARAMS mbox;
+
+    /*
+     * We use MessageBoxIndirect() because it allows us to specify a
+     * callback function for the Help button.
+     */
+    mbox.cbSize = sizeof(mbox);
+    mbox.hwndOwner = hwnd;
+    mbox.lpfnMsgBoxCallback = &verify_ssh_host_key_help;
+    mbox.dwLanguageId = LANG_NEUTRAL;
+
+    /* Do we have a help file? */
+    if (help_path)
+	help_button = MB_HELP;
+
     /*
      * Verify the key against the registry.
      */
@@ -747,13 +785,15 @@ void verify_ssh_host_key(void *frontend, char *host, int port, char *keytype,
 	return;
     if (ret == 2) {		       /* key was different */
 	int mbret;
-	char *message, *title;
-	message = dupprintf(wrongmsg, appname, keytype, fingerprint, appname);
-	title = dupprintf(mbtitle, appname);
-	mbret = MessageBox(NULL, message, title,
-			   MB_ICONWARNING | MB_YESNOCANCEL | MB_DEFBUTTON3);
-	sfree(message);
-	sfree(title);
+	mbox.lpszText = dupprintf(wrongmsg, appname, keytype, fingerprint,
+				  appname);
+	mbox.lpszCaption = dupprintf(mbtitle, appname);
+	mbox.dwContextHelpId = HELPCTXID(errors_hostkey_changed);
+	mbox.dwStyle = MB_ICONWARNING | MB_YESNOCANCEL | MB_DEFBUTTON3 |
+	    help_button;
+	mbret = MessageBoxIndirect(&mbox);
+	sfree((void *)mbox.lpszText);
+	sfree((void *)mbox.lpszCaption);
 	if (mbret == IDYES)
 	    store_host_key(host, port, keytype, keystr);
 	if (mbret == IDCANCEL)
@@ -761,13 +801,14 @@ void verify_ssh_host_key(void *frontend, char *host, int port, char *keytype,
     }
     if (ret == 1) {		       /* key was absent */
 	int mbret;
-	char *message, *title;
-	message = dupprintf(absentmsg, keytype, fingerprint, appname);
-	title = dupprintf(mbtitle, appname);
-	mbret = MessageBox(NULL, message, title,
-			   MB_ICONWARNING | MB_YESNOCANCEL | MB_DEFBUTTON3);
-	sfree(message);
-	sfree(title);
+	mbox.lpszText = dupprintf(absentmsg, keytype, fingerprint, appname);
+	mbox.lpszCaption = dupprintf(mbtitle, appname);
+	mbox.dwContextHelpId = HELPCTXID(errors_hostkey_absent);
+	mbox.dwStyle = MB_ICONWARNING | MB_YESNOCANCEL | MB_DEFBUTTON3 |
+	    help_button;
+	mbret = MessageBoxIndirect(&mbox);
+	sfree((void *)mbox.lpszText);
+	sfree((void *)mbox.lpszCaption);
 	if (mbret == IDYES)
 	    store_host_key(host, port, keytype, keystr);
 	if (mbret == IDCANCEL)

windows/window.c

@@ -166,8 +166,6 @@ static HPALETTE pal;
 static LPLOGPALETTE logpal;
 static RGBTRIPLE defpal[NALLCOLOURS];
 
-static HWND hwnd;
-
 static HBITMAP caretbm;
 
 static int dbltime, lasttime, lastact;

windows/winhelp.h

@@ -1,8 +1,10 @@
 /*
- * winhelp.h - define Windows Help context names for the controls
- * in the PuTTY config box.
+ * winhelp.h - define Windows Help context names. These match up with
+ * the \cfg{winhelp-topic} directives in the Halibut source.
  */
 
+/* These are used in the cross-platform configuration dialog code. */
+
 #define HELPCTX(x) P(WINHELP_CTX_ ## x)
 
 #define WINHELP_CTX_no_help NULL
@@ -122,3 +124,13 @@
 #define WINHELP_CTX_ssh_bugs_rsapad2 "ssh.bugs.rsapad2"
 #define WINHELP_CTX_ssh_bugs_pksessid2 "ssh.bugs.pksessid2"
 #define WINHELP_CTX_ssh_bugs_rekey2 "ssh.bugs.rekey2"
+
+/* These are used in Windows-specific bits of the frontend.
+ * We (ab)use "help context identifiers" (dwContextId) to identify them. */
+
+#define HELPCTXID(x) WINHELP_CTXID_ ## x
+
+#define WINHELP_CTX_errors_hostkey_absent "errors.hostkey.absent"
+#define WINHELP_CTXID_errors_hostkey_absent 1
+#define WINHELP_CTX_errors_hostkey_changed "errors.hostkey.changed"
+#define WINHELP_CTXID_errors_hostkey_changed 2

windows/winstuff.h

@@ -66,9 +66,10 @@ typedef struct terminal_tag Terminal;
 typedef HDC Context;
 
 /*
- * Window handles for the dialog boxes that can be running during a
+ * Window handles for the windows that can be running during a
  * PuTTY session.
  */
+GLOBAL HWND hwnd;	/* the main terminal window */
 GLOBAL HWND logbox;
 
 /*