Add api dox for nonce-tcp

Cherry-picked from commit e7a070db22ed4a84dc04a062255356c9f6c4c9c5 in
the dbus4win repository, trailing whitespace issues corrected by
tml@iki.fi.

dbus/dbus-nonce.c

@@ -92,11 +92,17 @@ do_check_nonce (int fd, const DBusString *nonce, DBusError *error)
   return result;
 }
 
-//PENDING(kdab) document
+/**
+ * reads the nonce from the nonce file and stores it in a string
+ *
+ * @param fname the file to read the nonce from
+ * @param nonce returns the nonce. Must be an initialized string, the nonce will be appended.
+ * @param error error object to report possible errors
+ * @return FALSE iff reading the nonce fails (error is set then)
+ */
 dbus_bool_t
 _dbus_read_nonce (const DBusString *fname, DBusString *nonce, DBusError* error)
 {
-  //PENDING(kdab) replace errno by DBusError
   FILE *fp;
   char buffer[17];
   buffer[sizeof buffer - 1] = '\0';
@@ -155,33 +161,6 @@ _dbus_accept_with_noncefile (int listen_fd, const DBusNonceFile *noncefile)
   return fd;
 }
 
-dbus_bool_t
-_dbus_generate_noncefilename (DBusString *buf, DBusError *error)
-{
-  dbus_bool_t ret;
-  DBusString randomStr;
-
-  _DBUS_ASSERT_ERROR_IS_CLEAR (error);
-
-  ret = _dbus_string_init (&randomStr);
-  if (!ret)
-    goto oom;
-  ret = _dbus_generate_random_ascii (&randomStr, 8);
-  if (!ret)
-    goto oom;
-  if (!_dbus_string_append (buf, _dbus_get_tmpdir())
-      || !_dbus_string_append (buf, DBUS_DIR_SEPARATOR "dbus_nonce-")
-      || !_dbus_string_append (buf, _dbus_string_get_const_data (&randomStr)) )
-    goto oom;
-
-  _dbus_string_free (&randomStr);
-  return TRUE;
-oom:
-  dbus_set_error (error, DBUS_ERROR_NO_MEMORY, NULL);
-  _dbus_string_free (&randomStr);
-  return FALSE;
-}
-
 static dbus_bool_t
 generate_and_write_nonce (const DBusString *filename, DBusError *error)
 {
@@ -206,6 +185,15 @@ generate_and_write_nonce (const DBusString *filename, DBusError *error)
   return ret;
 }
 
+/**
+ * sends the nonce over a given socket. Blocks while doing so.
+ *
+ * @param fd the file descriptor to write the nonce data to (usually a socket)
+ * @param noncefile the noncefile location to read the nonce from
+ * @param error contains error details if FALSE is returned
+ * @return TRUE iff the nonce was successfully sent. Note that this does not
+ * indicate whether the server accepted the nonce.
+ */
 dbus_bool_t
 _dbus_send_nonce(int fd, const DBusString *noncefile, DBusError *error)
 {
@@ -337,6 +325,13 @@ do_noncefile_create (DBusNonceFile *noncefile,
 }
 
 #ifdef DBUS_WIN
+/**
+ * creates a nonce file in a user-readable location and writes a generated nonce to it
+ *
+ * @param noncefile returns the nonce file location
+ * @param error error details if creating the nonce file fails
+ * @return TRUE iff the nonce file was successfully created
+ */
 dbus_bool_t
 _dbus_noncefile_create (DBusNonceFile *noncefile,
                         DBusError *error)
@@ -344,6 +339,13 @@ _dbus_noncefile_create (DBusNonceFile *noncefile,
     return do_noncefile_create (noncefile, error, /*use_subdir=*/FALSE);
 }
 
+/**
+ * deletes the noncefile and frees the DBusNonceFile object.
+ *
+ * @param noncefile the nonce file to delete. Contents will be freed.
+ * @param error error details if the nonce file could not be deleted
+ * @return TRUE
+ */
 dbus_bool_t
 _dbus_noncefile_delete (DBusNonceFile *noncefile,
                         DBusError *error)
@@ -356,6 +358,14 @@ _dbus_noncefile_delete (DBusNonceFile *noncefile,
 }
 
 #else
+/**
+ * creates a nonce file in a user-readable location and writes a generated nonce to it.
+ * Initializes the noncefile object.
+ *
+ * @param noncefile returns the nonce file location
+ * @param error error details if creating the nonce file fails
+ * @return TRUE iff the nonce file was successfully created
+ */
 dbus_bool_t
 _dbus_noncefile_create (DBusNonceFile *noncefile,
                         DBusError *error)
@@ -363,6 +373,13 @@ _dbus_noncefile_create (DBusNonceFile *noncefile,
     return do_noncefile_create (noncefile, error, /*use_subdir=*/TRUE);
 }
 
+/**
+ * deletes the noncefile and frees the DBusNonceFile object.
+ *
+ * @param noncefile the nonce file to delete. Contents will be freed.
+ * @param error error details if the nonce file could not be deleted
+ * @return TRUE
+ */
 dbus_bool_t
 _dbus_noncefile_delete (DBusNonceFile *noncefile,
                         DBusError *error)
@@ -376,6 +393,12 @@ _dbus_noncefile_delete (DBusNonceFile *noncefile,
 #endif
 
 
+/**
+ * returns the absolute file path of the nonce file
+ *
+ * @param noncefile an initialized noncefile object
+ * @return the absolute path of the nonce file
+ */
 const DBusString*
 _dbus_noncefile_get_path (const DBusNonceFile *noncefile)
 {
@@ -383,6 +406,16 @@ _dbus_noncefile_get_path (const DBusNonceFile *noncefile)
     return &noncefile->path;
 }
 
+/**
+ * reads data from a file descriptor and checks if the received data matches
+ * the data in the given noncefile.
+ *
+ * @param fd the file descriptor to read the nonce from
+ * @param noncefile the nonce file to check the received data against
+ * @param error error details on fail
+ * @return TRUE iff a nonce could be successfully read from the file descriptor
+ * and matches the nonce from the given nonce file
+ */
 dbus_bool_t
 _dbus_noncefile_check_nonce (int fd,
                              const DBusNonceFile *noncefile,

dbus/dbus-server-socket.c

@@ -73,7 +73,7 @@ socket_finalize (DBusServer *server)
   dbus_free (socket_server->fds);
   dbus_free (socket_server->watch);
   dbus_free (socket_server->socket_name);
-  _dbus_noncefile_delete (socket_server->noncefile, NULL); //PENDING(kdab) review error ignore
+  _dbus_noncefile_delete (socket_server->noncefile, NULL);
   dbus_free (socket_server->noncefile);
   dbus_free (server);
 }

dbus/dbus-sysdeps-win.c

@@ -44,6 +44,7 @@
 #include "dbus-hash.h"
 #include "dbus-sockets-win.h"
 #include "dbus-list.h"
+#include "dbus-nonce.h"
 #include "dbus-credentials.h"
 
 #include <windows.h>

dbus/dbus-transport-socket.c

@@ -1418,8 +1418,7 @@ _dbus_transport_open_socket(DBusAddressEntry  *entry,
       *transport_p = _dbus_transport_new_for_tcp_socket (host, port, family, noncefile, error);
       if (*transport_p == NULL)
         {
-          //PENDING(kdab)
-          //_DBUS_ASSERT_ERROR_IS_SET (error);
+          _DBUS_ASSERT_ERROR_IS_SET (error);
           return DBUS_TRANSPORT_OPEN_DID_NOT_CONNECT;
         }
       else

dbus/dbus-transport-win.c

@@ -52,19 +52,19 @@ _dbus_transport_open_platform_specific (DBusAddressEntry  *entry,
 {
   const char *method;
 
+  const char *host = dbus_address_entry_get_value (entry, "host");
+  const char *port = dbus_address_entry_get_value (entry, "port");
+  const char *family = dbus_address_entry_get_value (entry, "family");
+  const char *noncefile = dbus_address_entry_get_value (entry, "noncefile");
+
   method = dbus_address_entry_get_method (entry);
   _dbus_assert (method != NULL);
 
   if (strcmp (method, "nonce-tcp") != 0)
     {
-  _DBUS_ASSERT_ERROR_IS_CLEAR (error);
-  return DBUS_TRANSPORT_OPEN_NOT_HANDLED;
-}
-
-  const char *host = dbus_address_entry_get_value (entry, "host");
-  const char *port = dbus_address_entry_get_value (entry, "port");
-  const char *family = dbus_address_entry_get_value (entry, "family");
-  const char *noncefile = dbus_address_entry_get_value (entry, "noncefile");
+      _DBUS_ASSERT_ERROR_IS_CLEAR (error);
+      return DBUS_TRANSPORT_OPEN_NOT_HANDLED;
+    }
 
   if (port == NULL)
     {