passthru and multiple reader support.

New Features, library:
   - added passthru mode: pass thru can be used either as a card_type and an
   existing emulator, or as it's own emulator. When used as it's own emulator,
   only the passhthru card type is supported. Enabling Passhtru is a compile
   time option (you can build without it). It is still selected for at run-time

   - added argument parsing code for the NSS emulator. This allows the argument
   structure to move back to the emulator dependent directory. (This allows
   other emulators to be implemented without the application needing to know
   about emulator specific stuff.

   - added functions to get the reader name and id, and have the caller set
   the reader id.

   - added vevent_get_next_vevent() - non-blocking event grabber.

   - added string arguments to the card_type_init functions (currently not used).

   - added VCARD_DIRECT card type which passes all the apdus the the card type's
   last applet.

   - added function to optionally get the ATR from the card type emul instead
   of the emulator. NOTE: apps should now call vcard_get_atr rather than
   vcard_emul_get_atr.

   - Fixed the VCARD_ATR_PREFIX to take a constant signifying the number of
   additional historical bytes for the card emulator.

   - added usage statment.

New Features, vscclient.c
   - vscclient now handles multiple readers, assuming multiple readers are
   defined in qemu.

   - vscclient now calls the emul to parse the command line arguments.

   - vscclient has an option to enable passthru

   - vscclient now passes the real reader name to qemu

   - vscclient has 2 new commands:
       debug [level] -- sets the various levels of debugging output on the fly.
       list  -- lists all the active readers, their card state and their name.

1 files changed, 25 insertions, 13 deletions

diff --git a/README b/README
index 44579dc..870e590 100644
--- a/README
+++ b/README
@@ -37,7 +37,7 @@ this is in vcard_emul_nss.c.
 
 3) Emulation for new types of cards. The current implementation emulates the
 original DoD CAC standard with separate pki containers. This emulator lives in
-cac.c. More than one smart card emulator could be included. Other cards could
+cac.c. More than one card type emulator could be included. Other cards could
 be emulated as well, including PIV, newer versions of CAC, PKCS #15, etc.
 
 --------------------
@@ -125,25 +125,37 @@ that the CCID reader can call are:
   vreader_power_on, vreader_power_off, and vreader_xfer_bytes will return
   VREADER_NO_CARD.
 
-       /* not yet implemented */
-       VReaderStatus vreader_get_reader_name(VReader *reader, char *name,
-                                             int *len);
+       const char *vreader_get_name(VReader *reader);
 
-       /* not yet implemented */
-       VReaderID vreader_get_reader_id(VReader *reader);
+  This function returns the name of the reader. The name comes from the card
+  emulator level and is usually related to the name of the physical reader.
+
+       VReaderID vreader_get_id(VReader *reader);
+
+  This function returns the id of a reader. All readers start out with an id
+  of -1. The application can set the id with vreader_set_id.
+
+       VReaderStatus vreader_get_id(VReader *reader, VReaderID id);
+
+  This function sets the reader id. The application is responsible for making
+  sure that the id is unique for all readers it is actively using.
 
-       /* not yet implemented */
        VReader *vreader_find_reader_by_id(VReaderID id);
 
-       Event *event_wait_next_event();
+  This function returns the reader which matches the id. If two readers match,
+  only one is returned. The function returns NULL if the id is -1.
+
+       Event *vevent_wait_next_vevent();
 
   This function blocks waiting for reader and card insertion events. There
   will be one event for each card insertion, each card removal, each reader
   insertion and each reader removal. At start up, events are created for all
   the initial readers found, as well as all the cards that are inserted.
 
-       /* not yet implemented */
-       Event *event_get_next_event(); [ not blocking ]
+       Event *vevent_get_next_vevent();
+
+  This function returns a pending event if it exists, otherwise it returns
+  NULL. It does not block.
 
 ----------------
 Card Type Emulator: Adding a New Virtual Card Type
@@ -446,9 +458,9 @@ functions:
      void vcard_emul_get_atr(Vcard *card, unsigned char *atr, int *atr_len);
 
   Return the virtual ATR for the card. By convention this should be the value
-  VCARD_ATR_PREFIX followed by several ascii bytes related to this particular
-  emulator. For instance the NSS emulator returns {VCARD_ATR_PREFIX,
-  'N', 'S', 'S' }. Do ot return more data then *atr_len;
+  VCARD_ATR_PREFIX(size) followed by several ascii bytes related to this
+  particular emulator. For instance the NSS emulator returns
+  {VCARD_ATR_PREFIX(3), 'N', 'S', 'S' }. Do ot return more data then *atr_len;
 
      void vcard_emul_reset(VCard *card, VCardPower power)