Complete documentation for message functionality.

diff --git a/doc/p11-kit-docs.sgml b/doc/p11-kit-docs.sgml
index 2f7fdb26f54bc1792d37b179d30219ebbc7b8879..f0b95bf29e8b5c2bccc9a5e4131da5bc0fa2c2b5 100644 (file)
--- a/doc/p11-kit-docs.sgml
+++ b/doc/p11-kit-docs.sgml
@@ -19,6 +19,7 @@
                <xi:include href="xml/p11-kit.xml"/>
                <xi:include href="xml/p11-kit-uri.xml"/>
                <xi:include href="xml/p11-kit-util.xml"/>
+               <xi:include href="xml/p11-kit-future.xml"/>
        </chapter>
 
        <index id="api-index-full">

diff --git a/doc/p11-kit-sections.txt b/doc/p11-kit-sections.txt
index db1f4f7d16df4603832b084d9be347e1222907e5..36b9de2c384905dea141858e1d26f4b87e757148 100644 (file)
--- a/doc/p11-kit-sections.txt
+++ b/doc/p11-kit-sections.txt
@@ -56,3 +56,9 @@ CK_ULONG
 p11_kit_uri_result_t
 p11_kit_uri_type_t
 </SECTION>
+
+<SECTION>
+<FILE>p11-kit-future</FILE>
+p11_kit_be_quiet
+p11_kit_message
+</SECTION>
\ No newline at end of file

diff --git a/p11-kit/modules.c b/p11-kit/modules.c
index 757b4d2cb927fe2bf220043bc23557cf72d7149f..eae7de3d007b5826b466397eb419dd0b5dd37289 100644 (file)
--- a/p11-kit/modules.c
+++ b/p11-kit/modules.c
@@ -649,6 +649,9 @@ _p11_kit_initialize_registered_unlocked_reentrant (void)
  * Use p11_kit_finalize_registered() to finalize these registered modules once
  * the caller is done with them.
  *
+ * If this function fails, then an error message will be available via the
+ * p11_kit_message() function.
+ *
  * Returns: CKR_OK if the initialization succeeded, or an error code.
  */
 CK_RV
@@ -730,6 +733,9 @@ _p11_kit_finalize_registered_unlocked_reentrant (void)
  * process, then this function must be called the same number of times before
  * actual finalization will occur.
  *
+ * If this function fails, then an error message will be available via the
+ * p11_kit_message() function.
+ *
  * Returns: CKR_OK if the finalization succeeded, or an error code.
  */
 
@@ -936,6 +942,9 @@ p11_kit_registered_option (CK_FUNCTION_LIST_PTR module, const char *field)
  * Custom initialization arguments cannot be supported when multiple consumers
  * load the same module.
  *
+ * If this function fails, then an error message will be available via the
+ * p11_kit_message() function.
+ *
  * Returns: CKR_OK if the initialization was successful.
  */
 CK_RV
@@ -1001,6 +1010,9 @@ p11_kit_initialize_module (CK_FUNCTION_LIST_PTR module)
  * to use this function on registered modules if (and only if) they were
  * initialized using p11_kit_initialize_module() for some reason.
  *
+ * If this function fails, then an error message will be available via the
+ * p11_kit_message() function.
+ *
  * Returns: CKR_OK if the finalization was successful.
  */
 CK_RV
@@ -1061,6 +1073,9 @@ p11_kit_finalize_module (CK_FUNCTION_LIST_PTR module)
  * Custom initialization arguments cannot be supported when multiple consumers
  * load the same module.
  *
+ * If this function fails, then an error message will be available via the
+ * p11_kit_message() function.
+ *
  * Returns: CKR_OK if the initialization was successful.
  */
 CK_RV

diff --git a/p11-kit/util.c b/p11-kit/util.c
index dda470323e79a5be7834076d5ec1dc577aebf8e6..fdf434b85581518953a73bbddcd834119fc972e6 100644 (file)
--- a/p11-kit/util.c
+++ b/p11-kit/util.c
@@ -46,6 +46,16 @@
 #include <stdio.h>
 #include <string.h>
 
+/**
+ * SECTION:p11-kit-future
+ * @title: Future
+ * @short_description: Future Unstable API
+ *
+ * API that is not yet stable enough to be enabled by default. In all likelyhood
+ * this will be included in the next release. To use this API you must define a
+ * MACRO. See the p11-kit.h header for more details.
+ */
+
 #define MAX_MESSAGE 512
 static pthread_once_t key_once = PTHREAD_ONCE_INIT;
 static pthread_key_t message_buffer_key = 0;
@@ -180,6 +190,12 @@ _p11_message (const char* msg, ...)
        store_message_buffer (buffer, length);
 }
 
+/**
+ * p11_kit_be_quiet:
+ *
+ * Once this function is called, the p11-kit library will no longer print
+ * failure or warning messages to stderr.
+ */
 void
 p11_kit_be_quiet (void)
 {
@@ -188,6 +204,19 @@ p11_kit_be_quiet (void)
        _p11_unlock ();
 }
 
+/**
+ * p11_kit_message:
+ *
+ * Gets the failure message for a recently called p11-kit function, which
+ * returned a failure code on this thread. Not all functions set this message.
+ * Each function that does so, will note it in its documentation.
+ *
+ * If the most recent p11-kit function did not fail, then this will return NULL.
+ * The string is owned by the p11-kit library and is only valid on the same
+ * thread that the failed function executed on.
+ *
+ * Returns: The last failure message, or %NULL.
+ */
 const char*
 p11_kit_message (void)
 {