API dox update for recent changes

svn path=/trunk/kdesupport/qca/; revision=649889

include/QtCrypto/qca_keystore.h

@@ -47,6 +47,90 @@ namespace QCA
 	   Single entry in a KeyStore
 
 	   This is a container for any kind of object in a KeyStore
+	   (such as PGP keys, or X.509 certificates / private keys).
+
+	   KeyStoreEntry entities are normally accessed through the KeyStore,
+	   however it is possible to access KeyStoreEntry objects directly,
+	   using a persistent id().
+
+	   \code
+	   QString entry_id = someKeyStoreEntry.id();
+	   [ app saves entry_id to disk ]
+	   [ app quits ]
+	   ...
+	   [ app launches ]
+	   [ app reads entry_id from disk ]
+	   KeyStoreEntry entry(entry_id);
+	   printf("Entry name: [%s]\n", qPrintable(entry.name()));
+	   \endcode
+
+	   Keep in mind that retrieving a passive entry's content
+	   (e.g. with entry.certificate()) may return a null object.
+	   To ensure the entry is available, do:
+
+	   \code
+	   if(entry.ensureAvailable())
+	   {
+	   Certificate cert = entry.certificate();
+	   ...
+	   }
+	   \endcode
+
+	   ensureAvailable() blocks and may cause hardware access, but
+	   if it completes successfully then you may use the entry's
+	   content.  It also means, in the case of a Smart Card token,
+	   that it is probably inserted.
+
+	   To watch this id asynchronously, you would do:
+
+	   \code
+	   KeyStoreEntryWatcher *watcher = new KeyStoreEntryWatcher(entry);
+	   connect(watcher, SIGNAL(available()), SLOT(entry_available()));
+	   ...
+	   void entry_available()
+	   {
+	   // entry now available
+	   Certificate cert = watcher->entry().certificate();
+	   }
+	   \endcode
+
+	   Note that a provider can supply valid content objects even
+	   for unavailable entries, if they have enough metadata to
+	   provide that (qca-pkcs11 for example, puts the entire cert
+	   in the id).
+
+	   Now, even though an entry may be available, it does not
+	   mean you have access to use it for operations.  For
+	   example, a KeyBundle offered by a Smart Card that is
+	   available is guaranteed to give you valid objects, however
+	   as soon as you try to use the PrivateKey object for a
+	   signing operation, a PIN might be asked for.  You can call
+	   ensureAccess() if you want to synchronously provide the PIN
+	   early on:
+
+	   \code
+	   if(entry.ensureAccess())
+	   {
+	   // do private key stuff
+	   ...
+	   }
+	   \endcode
+
+	   Note that you don't have to call ensureAvailable() before
+	   ensureAccess().  Calling the latter is enough to imply
+	   both.
+
+	   After an application is configured to use a particular key,
+	   it is expected that its usual running procedure will be:
+
+	   - Construct KeyStoreEntry from the known id.
+	   - If the content object is not available, wait for it
+	   (with either ensureAvailable() or KeyStoreEntryWatcher).
+	   - Pass the content object(s) to a high level operation like TLS.
+
+	   In this case, any PIN prompting and private key operations
+	   would be caused/handled from the TLS object.
+
 	*/
 	class QCA_EXPORT KeyStoreEntry : public Algorithm
 	{
@@ -94,7 +178,32 @@ namespace QCA
 		*/
 		bool isNull() const;
 
+		/**
+		   Test if the key is available for use.
+
+		   A key is considered available if the KeyStore
+		   that it is part of is present.
+
+		   \sa ensureAvailable
+		   \sa isAccessible
+		*/
 		bool isAvailable() const;
+
+		/**
+		   Test if the key is currently accessible.
+
+		   This means that the private key part can be used
+		   at this time. For a smartcard, this means that all
+		   required operations (e.g. login / PIN entry) are
+		   completed.
+
+		   If isAccessible() is true, then the key
+		   is necessarily available (i.e. isAvailable() is
+		   also true).
+
+		   \sa ensureAccessible
+		   \sa isAvailable
+		*/
 		bool isAccessible() const;
 
 		/**
@@ -159,6 +268,7 @@ namespace QCA
 
 		/**
 		   Returns true if the entry is available, otherwise false.
+
 		   Available means that the retrieval functions (like
 		   keyBundle(), certificate(), pgpPublicKey(), etc) will
 		   return non-null objects.  Entries retrieved from a
@@ -167,6 +277,9 @@ namespace QCA
 		   on an already available entry may cause the entry to
 		   be refreshed.
 
+		   \sa isAvailable
+		   \sa ensureAccess
+
 		   \note This function is blocking.
 		*/
 		bool ensureAvailable();
@@ -175,6 +288,9 @@ namespace QCA
 		   Like ensureAvailable, but will also ensure
 		   that the token is inserted / PIN is provided 
 		   if needed.
+
+		   \sa isAccessible
+		   \sa ensureAvailable
 		*/
 		bool ensureAccess();
 
@@ -381,16 +497,25 @@ namespace QCA
 
 	   Access keystores, and monitor keystores for changes.
 
-	   If you are looking to use this class, you probably want to
-	   take a reference to the global KeyStoreManager, using the
-	   QCA::keyStoreManager() function. You then need to start()
+	   Before you can access a KeyStore, you must create a 
+	   KeyStoreManager. You then need to start()
 	   the KeyStoreManager, and either wait for the busyFinished()
 	   signal, or block using waitForBusyFinished().
+
+	   If you know the KeyStoreEntry that you need, you can
+	   use KeyStore passively, as described in the KeyStoreEntry
+	   documentation.
 	*/
 	class QCA_EXPORT KeyStoreManager : public QObject
 	{
 		Q_OBJECT
 	public:
+
+	        /**
+		   Create a new KeyStoreManager
+
+		   \param parent the parent for this object
+		*/
 		KeyStoreManager(QObject *parent = 0);
 		~KeyStoreManager();