Commit c8f73b36 authored by Frank Osterfeld's avatar Frank Osterfeld Committed by Ralf Habacker
Browse files

Add api dox for nonce-tcp

Cherry-picked from commit e7a070db22ed4a84dc04a062255356c9f6c4c9c5 in
the dbus4win repository, trailing whitespace issues corrected by
tml@iki.fi.
parent fbd21dd0
......@@ -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,
......
......@@ -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);
}
......
......@@ -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>
......
......@@ -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
......
......@@ -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)
{
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment