4 files changed, 99 insertions, 7 deletions
diff --git a/doc/reference/spice-gtk-docs.xml b/doc/reference/spice-gtk-docs.xml
index 2938960..57ef701 100644
--- a/doc/reference/spice-gtk-docs.xml
+++ b/doc/reference/spice-gtk-docs.xml
@@ -34,6 +34,8 @@
       <xi:include href="xml/channel-main.xml"/>
       <xi:include href="xml/channel-playback.xml"/>
       <xi:include href="xml/channel-record.xml"/>
+      <xi:include href="xml/channel-smartcard.xml"/>
+      <xi:include href="xml/smartcard-manager.xml"/>
     </chapter>
 
     <chapter>
diff --git a/doc/reference/spice-gtk-sections.txt b/doc/reference/spice-gtk-sections.txt
index 8ae04ba..715a3ba 100644
--- a/doc/reference/spice-gtk-sections.txt
+++ b/doc/reference/spice-gtk-sections.txt
@@ -187,6 +187,45 @@ spice_inputs_channel
 </SECTION>
 
 <SECTION>
+<FILE>channel-smartcard</FILE>
+<TITLE>SpiceSmartcardChannel</TITLE>
+spice_smartcard_channel
+SpiceSmartcardChannel
+SpiceSmartcardChannelClass
+<SUBSECTION Standard>
+SPICE_SMARTCARD_CHANNEL
+SPICE_IS_SMARTCARD_CHANNEL
+SPICE_TYPE_SMARTCARD_CHANNEL
+spice_smartcard_channel_get_type
+SPICE_SMARTCARD_CHANNEL_CLASS
+SPICE_IS_SMARTCARD_CHANNEL_CLASS
+SPICE_SMARTCARD_CHANNEL_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>smartcard-manager</FILE>
+<TITLE>SpiceSmartcardManager</TITLE>
+SPICE_TYPE_SMARTCARD_READER
+spice_smartcard_manager
+SpiceSmartcardManager
+SpiceSmartcardManagerClass
+spice_smartcard_reader_get_type
+spice_smartcard_manager_get
+spice_smartcard_manager_insert_card
+spice_smartcard_manager_remove_card
+spice_smartcard_reader_is_software
+SpiceSmartcardReader
+<SUBSECTION Standard>
+SPICE_SMARTCARD_MANAGER
+SPICE_IS_SMARTCARD_MANAGER
+SPICE_TYPE_SMARTCARD_MANAGER
+spice_smartcard_manager_get_type
+SPICE_SMARTCARD_MANAGER_CLASS
+SPICE_IS_SMARTCARD_MANAGER_CLASS
+SPICE_SMARTCARD_MANAGER_GET_CLASS
+</SECTION>
+
+<SECTION>
 <FILE>spice-widget</FILE>
 <TITLE>SpiceDisplay</TITLE>
 SpiceDisplay
diff --git a/gtk/channel-smartcard.c b/gtk/channel-smartcard.c
index 1591716..511152e 100644
--- a/gtk/channel-smartcard.c
+++ b/gtk/channel-smartcard.c
@@ -33,11 +33,19 @@
  * @short_description: smartcard authentication
  * @title: Smartcard Channel
  * @section_id:
- * @see_also: #SpiceChannel
+ * @see_also: #SpiceSmartcardManager, #SpiceSession
  * @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).
+ * This class doesn't provide useful methods, see #SpiceSession properties
+ * for a way to enable/disable this channel, and #SpiceSmartcardManager
+ * if you want to detect smartcard reader hotplug/unplug, and smartcard
+ * insertion/removal.
  */
 
 #define SPICE_SMARTCARD_CHANNEL_GET_PRIVATE(obj)                                  \
diff --git a/gtk/smartcard-manager.c b/gtk/smartcard-manager.c
index 003b563..72c8177 100644
--- a/gtk/smartcard-manager.c
+++ b/gtk/smartcard-manager.c
@@ -32,17 +32,18 @@
 #include "spice-marshal.h"
 
 /**
- * SECTION:spice-smartcard-manager
- * @short_description: the base smartcard-manager class
+ * SECTION:smartcard-manager
+ * @short_description: smartcard management
  * @title: Spice SmartcardManager
  * @section_id:
  * @see_also:
  * @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_reader_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);
@@ -507,6 +526,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 +550,17 @@ gboolean spice_smartcard_manager_insert_card(SpiceSmartcardManager *manager)
     return (status == VCARD_EMUL_OK);
 }
 
+/**
+ * spice_smartcard_manager_remove_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;