Better document struct pinentry.
authorNeal H. Walfield <neal@gnu.org>
Wed, 13 May 2015 12:21:19 +0000 (14:21 +0200)
committerNeal H. Walfield <neal@gnu.org>
Wed, 13 May 2015 12:22:04 +0000 (14:22 +0200)
* pinentry/pinentry.h (struct pinentry): Better document the various
fields.

pinentry/pinentry.h

index 2fd267e..7112637 100644 (file)
@@ -39,20 +39,28 @@ typedef enum {
 
 struct pinentry
 {
-  /* The window title, or NULL.  */
+  /* The window title, or NULL.  (Assuan: "SETTITLE TITLE".)  */
   char *title;
-  /* The description to display, or NULL.  */
+  /* The description to display, or NULL.  (Assuan: "SETDESC
+     DESC".) */
   char *description;
-  /* The error message to display, or NULL.  */
+  /* The error message to display, or NULL.  (Assuan: "SETERROR
+     MESSAGE".) */
   char *error;
-  /* The prompt to display, or NULL.  */
+  /* The prompt to display, or NULL.  (Assuan: "SETPROMPT
+     prompt".)  */
   char *prompt;
-  /* The OK button text to display, or NULL.  */
+  /* The OK button text to display, or NULL.  (Assuan: "SETOK
+     OK".)  */
   char *ok;
-  /* The Not-OK button text to display, or NULL.  */
+  /* The Not-OK button text to display, or NULL.  This is the text for
+     the alternative option shown by the third button.  (Assuan:
+     "SETNOTOK NOTOK".)  */
   char *notok;
-  /* The Cancel button text to display, or NULL.  */
+  /* The Cancel button text to display, or NULL.  (Assuan: "SETCANCEL
+     CANCEL".)  */
   char *cancel;
+
   /* The buffer to store the secret into.  */
   char *pin;
   /* The length of the buffer.  */
@@ -61,15 +69,19 @@ struct pinentry
      the user (0). */
   int pin_from_cache;
 
-  /* The name of the X display to use if X is available and supported.  */
+  /* The name of the X display to use if X is available and supported.
+     (Assuan: "OPTION display DISPLAY".)  */
   char *display;
-  /* The name of the terminal node to open if X not available or supported.  */
+  /* The name of the terminal node to open if X not available or
+     supported.  (Assuan: "OPTION ttyname TTYNAME".)  */
   char *ttyname;
-  /* The type of the terminal.  */
+  /* The type of the terminal.  (Assuan: "OPTION ttytype TTYTYPE".)  */
   char *ttytype;
-  /* The LC_CTYPE value for the terminal.  */
+  /* The LC_CTYPE value for the terminal.  (Assuan: "OPTION lc-ctype
+     LC_CTYPE".)  */
   char *lc_ctype;
-  /* The LC_MESSAGES value for the terminal.  */
+  /* The LC_MESSAGES value for the terminal.  (Assuan: "OPTION
+     lc-messages LC_MESSAGES".)  */
   char *lc_messages;
 
   /* True if debug mode is requested.  */
@@ -83,35 +95,38 @@ struct pinentry
   int enhanced;
 #endif
 
-  /* True if caller should grab the keyboard.  */
+  /* True if caller should grab the keyboard.  (Assuan: "OPTION grab"
+     or "OPTION no-grab".)  */
   int grab;
   /* The window ID of the parent window over which the pinentry window
-     should be displayed.  */
+     should be displayed.  (Assuan: "OPTION parent-wid WID".)  */
   int parent_wid;
 
   /* The name of an optional file which will be touched after a curses
-     entry has been displayed.  */
+     entry has been displayed.  (Assuan: "OPTION touch-file
+     FILENAME".)  */
   char *touch_file;
 
-  /* The user should set this to -1 if the user canceled the request,
-     and to the length of the PIN stored in pin otherwise.  */
+  /* The frontend should set this to -1 if the user canceled the
+     request, and to the length of the PIN stored in pin
+     otherwise.  */
   int result;
 
-  /* The user should set this if the NOTOK button was pressed.  */
+  /* The frontend should set this if the NOTOK button was pressed.  */
   int canceled;
 
-  /* The user should set this to true if an error with the local
+  /* The frontend should set this to true if an error with the local
      conversion occured. */
   int locale_err;
 
-  /* The user should set this to an gpg-error so that commands are
-     abale to return specific error codes.  This is an ugly hack due
-     to the fact that pinentry_cmd_handler_t return the length of the
-     passphrase or an negative error code.  */
+  /* The frontend should set this to a gpg-error so that commands are
+     able to return specific error codes.  This is an ugly hack due to
+     the fact that pinentry_cmd_handler_t returns the length of the
+     passphrase or a negative error code.  */
   int specific_err;
 
-  /* The user should set this to true if the window close button has
-     been used.  This flag is used in addition to a regular return
+  /* The frontend should set this to true if the window close button
+     has been used.  This flag is used in addition to a regular return
      value.  */
   int close_button;
 
@@ -122,10 +137,11 @@ struct pinentry
 
   /* If true a second prompt for the passphrase is shown and the user
      is expected to enter the same passphrase again.  Pinentry checks
-     that both match.  */
+     that both match.  (Assuan: "SETREPEAT".)  */
   char *repeat_passphrase;
 
-  /* The string to show if a repeated passphrase does not match.  */
+  /* The string to show if a repeated passphrase does not match.
+     (Assuan: "SETREPEATERROR ERROR".)  */
   char *repeat_error_string;
 
   /* Set to true if the passphrase has been entered a second time and
@@ -135,10 +151,12 @@ struct pinentry
   /* If this is not NULL, a passphrase quality indicator is shown.
      There will also be an inquiry back to the caller to get an
      indication of the quality for the passphrase entered so far.  The
-     string is used as a label for the quality bar.  */
+     string is used as a label for the quality bar.  (Assuan:
+     "SETQUALITYBAR LABEL".)  */
   char *quality_bar;
 
-  /* The tooltip to be show for the qualitybar.  Malloced or NULL.  */
+  /* The tooltip to be show for the qualitybar.  Malloced or NULL.
+     (Assuan: "SETQUALITYBAR_TT TOOLTIP".)  */
   char *quality_bar_tt;
 
   /* For the curses pinentry, the color of error messages.  */
@@ -151,19 +169,25 @@ struct pinentry
   /* Malloced and i18ned default strings or NULL.  These strings may
      include an underscore character to indicate an accelerator key.
      A double underscore represents a plain one.  */
+  /* (Assuan: "OPTION default-ok OK").  */
   char *default_ok;
+  /* (Assuan: "OPTION default-cancel CANCEL").  */
   char *default_cancel;
+  /* (Assuan: "OPTION default-prompt PROMPT").  */
   char *default_prompt;
+  /* (Assuan: "OPTION default-pwmngr
+     SAVE_PASSWORD_WITH_PASSWORD_MANAGER?").  */
   char *default_pwmngr;
 
   /* Whether we are allowed to read the password from an external
-     cache.  */
+     cache.  (Assuan: "OPTION allow-external-password-cache")  */
   int allow_external_password_cache;
 
   /* We only try the cache once.  */
   int tried_password_cache;
 
-  /* A stable identifier for the key.  */
+  /* A stable identifier for the key.  (Assuan: "SETKEYINFO
+     KEYINFO".)  */
   char *keyinfo;
 
   /* Whether we may cache the password (according to the user).  */