[Spice-devel] [PATCH 1/2] smartcard: add smartcard API doc

[Christophe Fergeau]

---
 gtk/channel-smartcard.c |    6 ++++-
 gtk/smartcard-manager.c |   50 ++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/gtk/channel-smartcard.c b/gtk/channel-smartcard.c
index 1591716..46aa037 100644
--- a/gtk/channel-smartcard.c
+++ b/gtk/channel-smartcard.c
@@ -37,7 +37,11 @@
  * @stability: In Development
  * @include: channel-smartcard.h
  *
- * TODO
+ * The Spice protocol defines a set of messages to forward smartcard
+ * information from the Spice client to the VM. This channel handles
+ * these messages. While it's mainly focus on smartcard readers and
+ * smartcards, it's also possible to use it with a software smartcard
+ * (ie a set of 3 certificates from the client machine).
  */
 
 #define SPICE_SMARTCARD_CHANNEL_GET_PRIVATE(obj)                                  \
diff --git a/gtk/smartcard-manager.c b/gtk/smartcard-manager.c
index 003b563..32ba613 100644
--- a/gtk/smartcard-manager.c
+++ b/gtk/smartcard-manager.c
@@ -40,9 +40,10 @@
  * @stability: Stable
  * @include: spice-smartcard-manager.h
  *
- * #SpiceSmartcardManager is the base class for the different kind of Spice
- * smartcard_manager connections, such as #SpiceMainSmartcardManager, or
- * #SpiceInputsSmartcardManager.
+ * #SpiceSmartcardManager monitors smartcard reader plugging/unplugging,
+ * and smartcard insertions/removals. It also provides methods to handle
+ * software smartcards (to emulate a smartcard reader/smartcard on the
+ * guest using 3 certificates available to the client).
  */
 
 /* ------------------------------------------------------------------ */
@@ -236,6 +237,15 @@ static SpiceSmartcardManager *spice_smartcard_manager_new(void)
 /* ------------------------------------------------------------------ */
 /* public api                                                         */
 
+/**
+ * spice_smartcard_manager_get
+ *
+ * SpiceSmartcardManager is a singleton, use this function to get a pointer
+ * to it. A new SpiceSmartcardManager instance will be created the first
+ * time this function is called
+ *
+ * Returns: a pointer to the SpiceSmartcardManager singleton
+ */
 SpiceSmartcardManager *spice_smartcard_manager_get(void)
 {
     static GOnce manager_singleton_once = G_ONCE_INIT;
@@ -385,6 +395,15 @@ static guint smartcard_monitor_add(SmartcardSourceFunc callback,
 
 #define SPICE_SOFTWARE_READER_NAME "Spice Software Smartcard"
 
+/**
+ * spice_smartcard_manager_is_software
+ * @reader: a #SpiceSmartcardReader
+ *
+ * Tests if @reader is a software (emulated) smartcard reader.
+ *
+ * Returns: TRUE if @reader is a software (emulated) smartcard reader,
+ * FALSE otherwise
+ */
 gboolean spice_smartcard_reader_is_software(SpiceSmartcardReader *reader)
 {
     g_return_val_if_fail(reader != NULL, FALSE);
@@ -454,6 +473,7 @@ end:
     return retval;
 }
 
+<<<<<<< HEAD
 static void smartcard_manager_init_helper(GSimpleAsyncResult *res,
                                           GObject *object,
                                           GCancellable *cancellable)
@@ -507,6 +527,19 @@ gboolean spice_smartcard_manager_init_finish(SpiceSession *session,
     return TRUE;
 }
 
+/**
+ * spice_smartcard_manager_insert_card
+ * @manager: a #SpiceSmartcardManager
+ *
+ * Simulates the insertion of a smartcard in the guest. Valid certificates
+ * must have been set in #SpiceSession::smartcard-certificates for software
+ * smartcard support to work. At the moment, only one software smartcard
+ * reader is supported, that's why there is no parameter to indicate which
+ * reader to insert the card in.
+ *
+ * Returns: TRUE if smartcard insertion was successfully simulated, FALSE
+ * if this failed, or if software smartcard support isn't enabled.
+ */
 gboolean spice_smartcard_manager_insert_card(SpiceSmartcardManager *manager)
 {
     VCardEmulError status;
@@ -518,6 +551,17 @@ gboolean spice_smartcard_manager_insert_card(SpiceSmartcardManager *manager)
     return (status == VCARD_EMUL_OK);
 }
 
+/**
+ * spice_smartcard_manager_insert_card
+ * @manager: a #SpiceSmartcardManager
+ *
+ * Simulates the removal of a smartcard in the guest. At the moment, only
+ * one software smartcard reader is supported, that's why there is no
+ * parameter to indicate which reader to insert the card in.
+ *
+ * Returns: TRUE if smartcard removal was successfully simulated, FALSE
+ * if this failed, or if software smartcard support isn't enabled.
+ */
 gboolean spice_smartcard_manager_remove_card(SpiceSmartcardManager *manager)
 {
     VCardEmulError status;
-- 
1.7.6