doxify client.h

and add documentation for enable_crypt() and enable_crypt().

diff --git a/audiod.c b/audiod.c
index 032b608cbc3acb32e537350fffba2a01aa27c099..e29894693762067d9d1c94767361a96cf87c8b17 100644 (file)
--- a/audiod.c
+++ b/audiod.c
@@ -991,7 +991,7 @@ static void status_post_select(__a_unused struct sched *s, struct task *t)
 
        t->ret = 1;
        if (!st->pcd || !st->pcd->loaded
-                       || st->pcd->status != CL_RECEIVING_SERVER_OUTPUT)
+                       || st->pcd->status != CL_RECEIVING)
                return;
        st->pcd->loaded = for_each_line(st->pcd->buf, st->pcd->loaded,
                &check_stat_line);

diff --git a/client.c b/client.c
index 69e0f3d3bf9c7382c3b78c012d5c1bfcd0fb6c7c..95dacd75f8a9d39c0e85f8118481b1600ecc88f8 100644 (file)
--- a/client.c
+++ b/client.c
@@ -59,7 +59,7 @@ static void client_event_handler(struct task *t)
                p->eof = 1;
                return;
        }
-       if (p->status == CL_SENDING_STDIN) {
+       if (p->status == CL_SENDING) {
                stdin_set_defaults(&sit);
                sit.buf = para_malloc(sit.bufsize),
                register_task(&sit.task);

diff --git a/client.h b/client.h
index 8f7b9a5dc1b47d4783da5ead2274cd87607a296f..1c9a8c22ae4dabd73a20547c8ce6bc195989e218 100644 (file)
--- a/client.h
+++ b/client.h
@@ -19,39 +19,72 @@
 /** \file client.h common client functions and exported symbols from client_common.c */
 
 #include <openssl/rc4.h>
+
+/**
+ * the different states of a connection from the view of the client
+ */
 enum {
+       /** tcp connection is established */
        CL_CONNECTED,
+       /** server sends the welcome message */
        CL_RECEIVED_WELCOME,
+       /** client sends the authentification request */
        CL_SENT_AUTH,
+       /** server sends a challenge */
        CL_RECEIVED_CHALLENGE,
+       /** clientd solves the challenge and sends the result */
        CL_SENT_CH_RESPONSE,
+       /** server accepts this authentication */
        CL_RECEIVED_PROCEED,
+       /** client sends the command */
        CL_SENT_COMMAND,
-       CL_SENDING_STDIN,
-       CL_RECEIVING_SERVER_OUTPUT
+       /** server expects data */
+       CL_SENDING,
+       /** client expects data */
+       CL_RECEIVING,
 };
 
 #define CLIENT_BUFSIZE 8192
 
+/**
+ * data specific to a client task
+ */
 struct private_client_data {
+       /** the state of the connection */
        int status;
+       /** the file descriptor */
        int fd;
+       /** the configuration (including the command) */
        struct client_args_info conf;
+       /** the config file for client options */
        char *config_file;
+       /** the RSA private key */
        char *key_file;
+       /** paraslash user name */
        char *user;
+       /** session key for receiving data */
        RC4_KEY rc4_recv_key;
+       /** session key for sending data */
        RC4_KEY rc4_send_key;
+       /** the client task structure */
        struct task task;
+       /** non-zero if task is unregistered */
        int eof;
+       /** the buffer used for handshake and receiving */
        char buf[CLIENT_BUFSIZE];
+       /** number of bytes loaded in \p buf */
        size_t loaded;
+       /** non-zero if the pre_select hook added \p fd to the read fd set */
        int check_r;
+       /** non-zero if the pre_select hook added \p fd to the write fd set */
        int check_w;
+       /** the decrypted challenge */
        long unsigned challenge_nr;
-       /* only used if stdin gets sent to para_server */
+       /** pointer to the data to be sent to para_server */
        char *inbuf;
+       /** number of bytes loaded in \p inbuf */
        size_t *in_loaded;
+       /** non-zero if input task encountered an eof or an errro condition */
        int *in_eof;
 };
 

diff --git a/client_common.c b/client_common.c
index 409c51df5973d51ec61f04091b322203c3c9a9e0..8bca7b7f04e237e4bfb0b477b828ae6678f9f2aa 100644 (file)
--- a/client_common.c
+++ b/client_common.c
@@ -129,13 +129,13 @@ void client_pre_select(struct sched *s, struct task *t)
                pcd->check_w = 1;
                return;
 
-       case CL_RECEIVING_SERVER_OUTPUT:
+       case CL_RECEIVING:
                if (pcd->loaded < CLIENT_BUFSIZE - 1) {
                        para_fd_set(pcd->fd, &s->rfds, &s->max_fileno);
                        pcd->check_r = 1;
                }
                return;
-       case CL_SENDING_STDIN:
+       case CL_SENDING:
                if (*pcd->in_loaded) {
                        PARA_INFO_LOG("loaded: %zd\n", *pcd->in_loaded);
                        para_fd_set(pcd->fd, &s->wfds, &s->max_fileno);
@@ -269,11 +269,11 @@ void client_post_select(struct sched *s, struct task *t)
                        return;
                t->ret = -E_HANDSHAKE_COMPLETE;
                if (strstr(pcd->buf, AWAITING_DATA_MSG))
-                       pcd->status = CL_SENDING_STDIN;
+                       pcd->status = CL_SENDING;
                else
-                       pcd->status = CL_RECEIVING_SERVER_OUTPUT;
+                       pcd->status = CL_RECEIVING;
                return;
-       case CL_SENDING_STDIN: /* FIXME: might block */
+       case CL_SENDING: /* FIXME: might block */
                PARA_INFO_LOG("loaded: %zd\n", *pcd->in_loaded);
                t->ret = send_bin_buffer(pcd->fd, pcd->inbuf, *pcd->in_loaded);
                if (t->ret <= 0) {
@@ -283,7 +283,7 @@ void client_post_select(struct sched *s, struct task *t)
                }
                *pcd->in_loaded = 0; /* FIXME: short writes */
                return;
-       case CL_RECEIVING_SERVER_OUTPUT:
+       case CL_RECEIVING:
                t->ret = client_recv_buffer(pcd);
                return;
        }

diff --git a/gui.ggo b/gui.ggo
index ab42144a718e167f318a394c73c10d93e558e06e..34cbdb1978359287291bc0a1a3b5dfd0554c8510 100644 (file)
--- a/gui.ggo
+++ b/gui.ggo
@@ -2,7 +2,7 @@ section "general options"
 option "auto_decode" a "auto-decode audio stream" flag on
 option "config_file" c "(default='~/.paraslash/gui.conf')" string typestr="filename" optional
 option "loglevel" l "set loglevel (0-6)" int typestr="level" default="4" optional
-option "timeout" t "set timeout" int typestr="milliseconds" default="300" optional
+option "timeout" t "set timeout" int typestr="milliseconds" default="30" optional
 option "stat_cmd" s "command to read server and audiod status data from" string typestr="command" default="para_audioc -t 100 stat" optional
 
 section "mapping keys to commands"

diff --git a/net.c b/net.c
index 28bc777d4dde6f56be5414d4d8d92aeb0d47ab6e..5a7eb9175427c2fcee0f4d3a2532870fb11dcc08 100644 (file)
--- a/net.c
+++ b/net.c
@@ -23,15 +23,26 @@
 #include "string.h"
 #include "error.h"
 
+
+/** \cond holds information about one encrypted connection */
 struct crypt_data {
        crypt_function *recv;
        crypt_function *send;
        void *private_data;
 };
-
 static struct crypt_data *crypt_data_array;
 static unsigned cda_size = 0;
+/** \endcond */
+
 
+/**
+ * activate encryption for one file descriptor
+ *
+ * \param fd the file descriptor
+ * \param recv the function used for decrypting received data
+ * \param send the function used for encrypting before sending
+ * \param private_data user data supplied by the caller
+ */
 void enable_crypt(int fd, crypt_function *recv, crypt_function *send,
        void *private_data)
 {
@@ -48,6 +59,13 @@ void enable_crypt(int fd, crypt_function *recv, crypt_function *send,
        PARA_INFO_LOG("rc4 encryption activated for fd %d\n", fd);
 }
 
+/**
+ * deactivate encryption for a given fd
+ *
+ * \param fd the file descriptor
+ *
+ * This must be called if and only if \p fd was activated via enable_crypt().
+ */
 void disable_crypt(int fd)
 {
        if (cda_size < fd + 1)