accept flags

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 67 insertions, 14 deletions

diff --git a/info/libpassphrase.texinfo b/info/libpassphrase.texinfo
index a5a27f1..d55d12d 100644
--- a/info/libpassphrase.texinfo
+++ b/info/libpassphrase.texinfo
@@ -50,10 +50,19 @@ Texts. A copy of the license is included in the section entitled
 
 
 @menu
-* Overview::                        Brief overview of libpassphrase.
-* Advanced Programming Interface::  How to take advantage of libpassphrase in your application.
-* Configuring libpassphrase::       How to configure libpassphrase.
-* GNU Free Documentation License::  Copying and sharing this manual.
+* Overview::                           Brief overview of libpassphrase.
+* Application Programming Interface::  How to take advantage of libpassphrase in your application.
+* Configuring libpassphrase::          How to configure libpassphrase.
+* GNU Free Documentation License::     Copying and sharing this manual.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Application Programming Interface
+
+* Example::                            Example of how to use libpassphrase
+
+@end detailmenu
 @end menu
 
 
@@ -77,11 +86,11 @@ or write your own replacement.
 
 
 
-@node Advanced Programming Interface
-@chapter Advanced Programming Interface
+@node Application Programming Interface
+@chapter Application Programming Interface
 
 @menu
-* Example::   Example of how to use libpassphrase
+* Example::                            Example of how to use libpassphrase
 @end menu
 
 
@@ -134,6 +143,37 @@ you should wipe it and free it.
 and is equivalent to
 @code{passphrase_read2(STDIN_FILENO, 0)}.
 
+@code{flags} is used to tweak the behaviour
+if the function. It should be a combination
+of the constants
+@table @code
+@item PASSPHRASE_READ_EXISTING
+@code{passphrase_read2} shall not do any thing
+special, just accept the passphrase. This should
+be used when getting authentication. Should not
+be combined with @code{PASSPHRASE_READ_NEW}.
+@item PASSPHRASE_READ_NEW
+@code{passphrase_read2} shall draw a pasphrase
+strenght meter if such capability is available.
+This should be used when create a new passphrase.
+Should not be combined with @code{PASSPHRASE_READ_EXISTING}.
+@item PASSPHRASE_READ_SCREEN_FREE
+@code{passphrase_read2} may do as it please with
+the the screen. This is only used if combined with
+@code{PASSPHRASE_READ_NEW} and not with
+@code{PASSPHRASE_READ_BELOW_FREE}. @code{passphrase_read2}
+will create make a line below the new current
+line and use that line to draw the passphrase
+strength meter if such capability is available.
+@item PASSPHRASE_READ_BELOW_FREE
+@code{passphrase_read2} may do as it please with
+the line below the current line. This is only used
+if combined with @code{PASSPHRASE_READ_NEW}.
+@code{passphrase_read2} will draw the passphrase
+strength meter on the line below if such capability
+is available.
+@end table
+
 @item  void passphrase_reenable_echo1(int fdin)
 @itemx void passphrase_reenable_echo(void)
 When you have read the passphrase you should
@@ -175,29 +215,41 @@ been disabled.
 @section Example
 
 @example
-#include <passphrase.h>  /* For libpassphrase */
-#include <stdio.h>       /* For output        */
-#include <stdlib.h>      /* For free          */
-#include <string.h>      /* For strlen        */
+#include <passphrase.h>  /* For libpassphrase  */
+#include <stdio.h>       /* For output         */
+#include <stdlib.h>      /* For free           */
+#include <string.h>      /* For strlen         */
+#include <fcntl.h>       /* For open, O_RDONLY */
+#include <unistd.h>      /* For close          */
 
 int main(int argc, char** argv)
 @{
   /* Variables for the passphrase */
   char* passphrase;
   
+  /* Get file descriptor to the terminal */
+  int fd = open("/dev/tty", O_RDONLY);
+  if (fd == -1)
+    @{
+      perror(*argv);
+      return 1;
+    @}
+  
   /* Hide the passphrase */
-  passphrase_disable_echo();
+  passphrase_disable_echo1(fd);
   
   /* Do things needed before reading the passphrase */
   printf("Passphrase: ");
   fflush(stdout);
   
   /* Read the passphrase */
-  passphrase = passphrase_read();
+  passphrase = passphrase_read2(fd, PASSPHRASE_READ_NEW |
+                                    PASSPHRASE_READ_SCREEN_FREE);
   if (passphrase == NULL)
    @{
     /* Something went wrong, print what and exit */
     perror(*argv);
+    close(fd);
     return 1;
    @}
   
@@ -209,9 +261,10 @@ int main(int argc, char** argv)
   free(passphrase);
   
   /* Stop hiding user input */
-  passphrase_reenable_echo();
+  passphrase_reenable_echo1(fd);
   
   /* End of program */
+  close(fd);
   return 0;
   
   /* `argc` was never used */