From 89b8716985a992419cf65fc3d29a2f20372b9c52 Mon Sep 17 00:00:00 2001 From: Igor Socec Date: Tue, 18 Mar 2014 18:48:37 +0100 Subject: [PATCH] improved comments of globally used functions --- client.c | 26 ++++++++++++--- moxerver.h | 93 ++++++++++++++++++++++++++++++++++++++++++++++++------ server.c | 32 ++++++++++++++++--- telnet.c | 24 ++++++++++++-- 4 files changed, 153 insertions(+), 22 deletions(-) diff --git a/client.c b/client.c index 57b5bbc..2c78dd4 100644 --- a/client.c +++ b/client.c @@ -1,7 +1,12 @@ #include "moxerver.h" -/* Closes client connection. */ +/** + * Closes client connection. + * + * Returns: + * 0 always, but internally tries closing again if it fails. + */ int client_close(struct client_t *client) { /* force closing in case of error */ if (close(client->socket) == -1) { @@ -12,7 +17,14 @@ int client_close(struct client_t *client) { return 0; } -/* Reads incoming data from client to client data buffer. */ +/** + * Reads data from client into client data buffer. + * + * Returns: + * - number of read bytes on success, + * - negative ENODATA value (-ENODATA) if client disconnected, + * - negative errno value set appropriately by error in reading + */ int client_read(struct client_t *client) { int len; @@ -26,7 +38,7 @@ int client_read(struct client_t *client) { /* a disconnected client socket is ready for reading but read returns 0 */ if (len == 0) { fprintf(stderr, "[%s:%d] no data available from client\n", __func__, __LINE__); - return -ENODATA; //TODO document this in header + return -ENODATA; } //TODO let's print received bytes during development phase... @@ -46,7 +58,13 @@ int client_read(struct client_t *client) { return len; } -/* Sends data from a buffer to client. */ +/** + * Sends data from a buffer to client. + * + * Returns: + * - number of sent bytes on success, + * - negative errno value set appropriately by error in sending + */ int client_write(struct client_t *client, char *databuf, int datalen) { int len; diff --git a/moxerver.h b/moxerver.h index 9c36586..fac79c3 100644 --- a/moxerver.h +++ b/moxerver.h @@ -14,6 +14,8 @@ #define DATA_BUFLEN 128 #define DEV_PATH 32 + +/* Structures used for communication parameters. */ struct server_t { int socket; /* server socket */ struct sockaddr_in address; /* server address information */ @@ -41,29 +43,100 @@ struct client_t client; /* connected client structure */ //TODO working with on struct tty_t tty_dev; /* connected tty device */ -/* Sets up the server on specific port, binds to a socket and listens for client connections. */ +/* Functions handling server operation. */ + +/** + * Sets up the server on specific port, binds to a socket and listens for client connections. + * + * Returns: + * - 0 on success, + * - negative errno value set appropriately by error in setup process + */ int server_setup(struct server_t *server, unsigned int port); -/* Closes the server. */ + +/** + * Closes the server socket. + * + * Returns: + * 0 always, but internally tries closing again if it fails. + */ int server_close(struct server_t *server); -/* Accepts incoming client connection. */ + +/** + * Accepts incoming client connection. + * + * Returns: + * - 0 on success, + * - negative errno value set appropriately by error in setup process + */ int server_accept(struct server_t *server, struct client_t *accepted_client); -/* Rejects incoming client connection. */ + +/** + * Rejects incoming client connection. + * + * Returns: + * 0 always, errors with rejected client are ignored + */ int server_reject(struct server_t *server); -/* Closes client connection. */ +/* Functions handling communication with clients. */ + +/** + * Closes client connection. + * + * Returns: + * 0 always, but internally tries closing again if it fails. + */ int client_close(struct client_t *client); -/* Reads incoming data from client to client data buffer. */ + +/** + * Reads data from client into client data buffer. + * + * Returns: + * - number of read bytes on success, + * - negative ENODATA value (-ENODATA) if client disconnected, + * - negative errno value set appropriately by error in reading + */ int client_read(struct client_t *client); -/* Sends data from a buffer to client. */ + +/** + * Sends data from a buffer to client. + * + * Returns: + * - number of sent bytes on success, + * - negative errno value set appropriately by error in sending + */ int client_write(struct client_t *client, char *databuf, int datalen); -/* Tells client to go into "character" mode. */ +/* Functions handling details related to telnet protocol. */ + +/** + * Tells client to go into "character" mode. + * + * Returns: + * - 0 on success + * - negative value if error occurred + */ int telnet_set_character_mode(struct client_t *client); -/* Handles special characters in data buffer after receiving them from client. */ + +/** + * Handles special characters in data buffer after receiving them from client. + * Used to filter out handshake commands of telnet protocol. + * + * Returns: + * 0 always + */ int telnet_handle_client_read(char *databuf, int *datalen); -/* Handles special characters in data buffer before sending to client. */ + +/** + * Handles special characters in data buffer before sending to client. + * Used for echoing characters correctly to telnet client. + * + * Returns: + * 0 always + */ int telnet_handle_client_write(char *databuf, int *datalen); diff --git a/server.c b/server.c index fb9c819..b768322 100644 --- a/server.c +++ b/server.c @@ -1,7 +1,13 @@ #include "moxerver.h" -/* Sets up the server on specific port, binds to a socket and listens for client connections. */ +/** + * Sets up the server on specific port, binds to a socket and listens for client connections. + * + * Returns: + * - 0 on success, + * - negative errno value set appropriately by error in setup process + */ int server_setup(struct server_t *server, unsigned int port) { int namelen, opt; @@ -47,7 +53,7 @@ int server_setup(struct server_t *server, unsigned int port) { } if (ntohs(server->address.sin_port) != port) { fprintf(stderr, "[%s:%d] error: could not assign port %u\n", __func__, __LINE__, port); - return -1; + return -1; //TODO find appropriate errno for this } /* save server port number */ server->port = port; @@ -63,7 +69,12 @@ int server_setup(struct server_t *server, unsigned int port) { return 0; } -/* Closes the server. */ +/** + * Closes the server socket. + * + * Returns: + * 0 always, but internally tries closing again if it fails. + */ int server_close(struct server_t *server) { /* force closing in case of error */ if (close(server->socket) == -1) { @@ -73,7 +84,13 @@ int server_close(struct server_t *server) { return 0; } -/* Accepts incoming client connection. */ +/** + * Accepts incoming client connection. + * + * Returns: + * - 0 on success, + * - negative errno value set appropriately by error in setup process + */ int server_accept(struct server_t *server, struct client_t *accepted_client) { int namelen; @@ -102,7 +119,12 @@ int server_accept(struct server_t *server, struct client_t *accepted_client) { return 0; } -/* Rejects incoming client connection. */ +/** + * Rejects incoming client connection. + * + * Returns: + * 0 always, errors with rejected client are ignored + */ int server_reject(struct server_t *server) { int namelen; diff --git a/telnet.c b/telnet.c index 72631f6..2c76c2a 100644 --- a/telnet.c +++ b/telnet.c @@ -70,7 +70,13 @@ static int telnet_handle_command(char *databuf, int datalen) { return 0; } -/* Tells client to go into "character" mode. */ +/** + * Tells client to go into "character" mode. + * + * Returns: + * - 0 on success + * - negative value if error occurred + */ int telnet_set_character_mode(struct client_t *client) { int err = 0; @@ -85,7 +91,13 @@ int telnet_set_character_mode(struct client_t *client) { return err; } -/* Handles special characters in data buffer after receiving them from client. */ +/** + * Handles special characters in data buffer after receiving them from client. + * Used to filter out handshake commands of telnet protocol. + * + * Returns: + * 0 always + */ int telnet_handle_client_read(char *databuf, int *datalen) { int i; @@ -111,7 +123,13 @@ int telnet_handle_client_read(char *databuf, int *datalen) { return 0; } -/* Handles special characters in data buffer before sending to client. */ +/** + * Handles special characters in data buffer before sending to client. + * Used for echoing characters correctly to telnet client. + * + * Returns: + * 0 always + */ int telnet_handle_client_write(char *databuf, int *datalen) { int i;