vscard_common: fixes

 * removed ReaderResponse, will use Error instead with code==VSC_SUCCESS.
 * added error code VSC_SUCCESS.
 * adaded Flush and FlushComplete, remove Reconnect.
 * updated comments.

1 files changed, 56 insertions, 27 deletions

diff --git a/vscard_common.h b/vscard_common.h
index de16506..b78f487 100644
--- a/vscard_common.h
+++ b/vscard_common.h
@@ -1,12 +1,17 @@
 /* Virtual Smart Card protocol definition
  *
  * This protocol is between a host using virtual smart card readers,
- * and a client implementing the smart cards, perhaps by emulating them or by
+ * and a client providing the smart cards, perhaps by emulating them or by
  * access to real cards.
  *
+ * Definitions for this protocol:
+ *  Host   - user of the card
+ *  Client - owner of the card
+ *
  * The current implementation passes the raw APDU's from 7816 and additionally
  * contains messages to setup and teardown readers, handle insertion and
- * removal of cards, negotiate the protocol and provide for error responses.
+ * removal of cards, negotiate the protocol via capabilities and provide
+ * for error responses.
  *
  * Copyright (c) 2011 Red Hat.
  *
@@ -40,42 +45,53 @@
  * something that cannot be accomodated with the existing protocol.
  */
 
-#define VSCARD_VERSION MAKE_VERSION(0,0,1)
+#define VSCARD_VERSION MAKE_VERSION(0,0,2)
 
 #define VSCARD_UNDEFINED_READER_ID -1
 #define VSCARD_MINIMAL_READER_ID    0
 
 typedef enum {
-    VSC_Init=1,
+    VSC_Init = 1,
     VSC_Error,
     VSC_ReaderAdd,
-    VSC_ReaderAddResponse,
     VSC_ReaderRemove,
     VSC_ATR,
     VSC_CardRemove,
     VSC_APDU,
-    VSC_Reconnect
+    VSC_Flush,
+    VSC_FlushComplete
 } VSCMsgType;
 
 typedef enum {
+    VSC_SUCCESS=0,
     VSC_GENERAL_ERROR=1,
     VSC_CANNOT_ADD_MORE_READERS,
+    VSC_CARD_ALREAY_INSERTED,
 } VSCErrorCode;
 
+<<<<<<<
 typedef uint32_t reader_id_t;
+=======
+#define VSCARD_UNDEFINED_READER_ID  0xffffffff
+#define VSCARD_MINIMAL_READER_ID    0
+>>>>>>>
 
 #define VSCARD_MAGIC (*(uint32_t*)"VSCD")
 
+/* Header
+ * Each message starts with the header. The reader_id
+ * value is only relevant
+ */
 typedef struct VSCMsgHeader {
-    VSCMsgType type;
-    reader_id_t   reader_id;
+    uint32_t   type;
+    uint32_t   reader_id;
     uint32_t   length;
     uint8_t    data[0];
 } VSCMsgHeader;
 
 /* VSCMsgInit               Client <-> Host
- * Client sends, Host replies with same.
- * Client fills it's own capabilities, host replies with it's capabilities.
+ * Client sends it on connection, with its own capabilities.
+ * Host replies with VSCMsgInit filling in its capabilities.
  *
  * It is not meant to be used for negotiation, i.e. sending more then
  * once from any side, but could be used for that in the future.
@@ -83,60 +99,73 @@ typedef struct VSCMsgHeader {
 typedef struct VSCMsgInit {
     uint32_t   magic;
     uint32_t   version;
-    uint32_t   capabilities[1]; /* client must check length,
+    uint32_t   capabilities[1]; /* receiver must check length,
                                    array may grow in the future*/
 } VSCMsgInit;
 
 /* VSCMsgError              Client <-> Host
+ * This message is a response to any of:
+ *  Reader Add
+ *  Reader Remove
+ *  Card Remove
+ * If the operation was successful then VSC_SUCCESS
+ * is returned, other wise a specific error code.
  * */
 typedef struct VSCMsgError {
     uint32_t   code;
 } VSCMsgError;
 
 /* VSCMsgReaderAdd          Client -> Host
- * Host replies with allocated reader id in ReaderAddResponse
- * name - name of the reader on client side.
+ * Host replies with allocated reader id in VSCMsgError with code==SUCCESS.
+ *
+ * name - name of the reader on client side, UTF-8 encoded. Only used
+ *  for client presentation (may be translated to the device presented to the guest),
+ * protocol wise only reader_id 
  * */
 typedef struct VSCMsgReaderAdd {
     uint8_t    name[0];
 } VSCMsgReaderAdd;
 
-/* VSCMsgReaderAddResponse  Host -> Client
- * Reply to ReaderAdd
- * */
-typedef struct VSCMsgReaderAddResponse {
-} VSCMsgReaderAddResponse;
-
 /* VSCMsgReaderRemove       Client -> Host
+ * The client's reader has been removed.
  * */
 typedef struct VSCMsgReaderRemove {
 } VSCMsgReaderRemove;
 
 /* VSCMsgATR                Client -> Host
- * Answer to reset. Sent for card insertion or card reset.
+ * Answer to reset. Sent for card insertion or card reset. The reset/insertion
+ * happens on the client side, they do not require any action from the host.
  * */
 typedef struct VSCMsgATR {
     uint8_t     atr[0];
 } VSCMsgATR;
 
 /* VSCMsgCardRemove         Client -> Host
+ * The client card has been removed.
  * */
 typedef struct VSCMsgCardRemove {
 } VSCMsgCardRemove;
 
 /* VSCMsgAPDU               Client <-> Host
+ * Main reason of existance. Transfer a single APDU in either direction.
  * */
 typedef struct VSCMsgAPDU {
     uint8_t    data[0];
 } VSCMsgAPDU;
 
-/* VSCMsgReconnect          Host -> Client
- * Contains new host address as two strings for IPv4 and
- * IPv6 support.
+/* VSCMsgFlush               Host -> Client
+ * Request client to send a FlushComplete message when it is done
+ * servicing all outstanding APDUs
+ * */
+typedef struct VSCMsgFlush {
+} VSCMsgFlush;
+
+/* VSCMsgFlush               Client -> Host
+ * Client response to Flush after all APDUs have been processed and
+ * responses sent.
  * */
-typedef struct VSCMsgReconnect {
-    char       host[128];
-    char       port[128];
-} VSCMsgReconnect;
+typedef struct VSCMsgFlushComplete {
+} VSCMsgFlushComplete;
 
 #endif // VSCARD_COMMON_H
+