From 6da750c95c6d693b71815258a7ec8e6d2d89cd16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Eckl=2C=20M=C3=A1t=C3=A9?= <ecklm94@gmail.com>
Date: Fri, 27 May 2016 00:46:11 +0200
Subject: [PATCH] =?UTF-8?q?Dokument=C3=A1ci=C3=B3=20hozz=C3=A1adva?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 include/IPC_US_communicator.h | 21 +++++++++++++---
 include/command.h             |  9 +++----
 include/dns_answer.h          |  6 ++---
 include/dns_db.h              |  4 +++
 include/dns_flags.h           | 10 ++++----
 include/dns_server.h          | 47 +++++++++++++++++++++++++++++++----
 include/logger.h              | 27 ++++++++++++++++++++
 include/record.h              |  3 +++
 include/udp_packet_wp.h       |  2 +-
 src/IPC_US_communicator.cpp   | 16 ++++++------
 10 files changed, 113 insertions(+), 32 deletions(-)

diff --git a/include/IPC_US_communicator.h b/include/IPC_US_communicator.h
index f5c0069..75ecd03 100644
--- a/include/IPC_US_communicator.h
+++ b/include/IPC_US_communicator.h
@@ -12,20 +12,33 @@
 
 #include "udp_socket_wp.h"
 
+/**
+ * A communicator class to implement IPC between the server
+ * (running in the background) and a controller task.
+ * It implements between two pre-set sockets.
+ */
 class IPC_US_communicator
 {
-	const bool master;
-	general_sockaddr_wp master_sockaddr;
-	general_sockaddr_wp slave_sockaddr;
-	udp_socket_wp comm_sock;
+	const bool server; /** If tha object is a server */
+	general_sockaddr_wp server_sockaddr; /** Sockaddr for the server */
+	general_sockaddr_wp controller_sockaddr; /** Sockaddr for the controller */
+	udp_socket_wp comm_sock; /** Socket to which messages will be sent */
 	IPC_US_communicator(const IPC_US_communicator& orig);
 public:
 	IPC_US_communicator(std::string socket_path, const bool master);
 
 	virtual ~IPC_US_communicator();
 
+	/**
+	 * Returns the received data from the other side.
+	 * @return Received data in string
+	 */
 	std::string recv_data();
 
+	/**
+	 * Send a string message to the other side.
+	 * @param data The message to send
+	 */
 	void send_data(const std::string& data);
 };
 
diff --git a/include/command.h b/include/command.h
index d36e94e..f60efcc 100644
--- a/include/command.h
+++ b/include/command.h
@@ -1,9 +1,3 @@
-/*
- * To change this license header, choose License Headers in Project Properties.
- * To change this template file, choose Tools | Templates
- * and open the template in the editor.
- */
-
 /* 
  * File:   command.h
  * Author: Eckl Máté <ecklm94@gmail.com>
@@ -14,6 +8,9 @@
 #ifndef COMMAND_H
 #define COMMAND_H
 
+/**
+ * Enum of possible command which may be sended to a server.
+ */
 enum command
 {
 	STATISTICS, KILL
diff --git a/include/dns_answer.h b/include/dns_answer.h
index d8b1e3d..5a71039 100644
--- a/include/dns_answer.h
+++ b/include/dns_answer.h
@@ -40,8 +40,8 @@
  */
 class dns_answer: public dns_question
 {
-	uint32_t ttl;
-	uint16_t rd_length;
+	uint32_t ttl; /** Time To Live */
+	uint16_t rd_length; /** Total length of the rdata field in bytes */
 	char *rdata; /** There is no '\0' at the end. */
 protected:
 	/**
@@ -62,7 +62,7 @@ public:
 	/**
 	 * @return Full size of the answer object including the length of rdata
 	 */
-	virtual size_t get_size() const;
+	virtual size_t get_size() const override;
 
 	/**
 	 * @return TTL in host byte order
diff --git a/include/dns_db.h b/include/dns_db.h
index d34af07..6055550 100644
--- a/include/dns_db.h
+++ b/include/dns_db.h
@@ -16,6 +16,10 @@
 #include "record.h"
 
 // https://www.sqlite.org/cintro.html
+
+/**
+ * Database handler wrapper class that uses sqlite to execute readonly queries.
+ */
 class dns_db
 {
 	static bool map_initialized; /** Helps to mage readable_DNS_types singleton. */
diff --git a/include/dns_flags.h b/include/dns_flags.h
index 93ce888..cd5ecd4 100644
--- a/include/dns_flags.h
+++ b/include/dns_flags.h
@@ -23,13 +23,13 @@
  */
 
 /** The QR bit indicates whether the header is for a query or a response. */
-#define DNS_FLAG_QR_QUERY 0x0000 
+//#define DNS_FLAG_QR_QUERY 0x0000 
 #define DNS_FLAG_QR_RESPONSE 0x8000
 
 // https://tools.ietf.org/html/rfc6895#section-2.2
 #define DNS_FLAG_OPCODE_SHIFT 15
 #define DNS_FLAG_OPCODE_MASK 0x7800 // 01111000 00000000
-#define DNS_FLAG_OPCODE_STANDARD_QUERY 0x0000<<DNS_FLAG_OPCODE_SHIFT
+//#define DNS_FLAG_OPCODE_STANDARD_QUERY 0x0000<<DNS_FLAG_OPCODE_SHIFT
 #define DNS_FLAG_OPCODE_STATUS 0x0002<<DNS_FLAG_OPCODE_SHIFT
 #define DNS_FLAG_OPCODE_UNASSIGNED 0x0003<<DNS_FLAG_OPCODE_SHIFT
 #define DNS_FLAG_OPCODE_NOTIFY 0x0004<<DNS_FLAG_OPCODE_SHIFT
@@ -38,12 +38,12 @@
 //-- Only meaningfull in the response packet --//
 #define DNS_FLAG_AA_MASK 0x0400
 #define DNS_FLAG_AA_AUTHORITATIVE 0x0400
-#define DNS_FLAG_AA_RECURSIVE 0x0000
+//#define DNS_FLAG_AA_RECURSIVE 0x0000
 //---------------------------------------------//
 
 #define DNS_FLAG_TC_MASK 0x0200
 #define DNS_FLAG_TC_TRUNCATED 0x0200
-#define DNS_FLAG_TC_NOT_TRUNCATED 0x0000
+//#define DNS_FLAG_TC_NOT_TRUNCATED 0x0000
 
 #define DNS_FLAG_RD_MASK 0x0100
 #define DNS_FLAG_RD_RECURSION_DESIRED 0x0100
@@ -64,7 +64,7 @@
 
 // https://tools.ietf.org/html/rfc6895#section-2.3
 #define DNS_FLAG_RCODE_MASK 0x000F
-#define DNS_FLAG_RCODE_NOERR 0x0000
+//#define DNS_FLAG_RCODE_NOERR 0x0000
 #define DNS_FLAG_RCODE_FORMERR 0x0001
 #define DNS_FLAG_RCODE_SERVFAIL 0x0002
 #define DNS_FLAG_RCODE_NXDOMAIN 0x0003
diff --git a/include/dns_server.h b/include/dns_server.h
index 5abb7fd..66552fe 100644
--- a/include/dns_server.h
+++ b/include/dns_server.h
@@ -15,15 +15,31 @@
 class dns_server
 {
 private:
-	dns_db db;
-	udp_socket_wp socket;
-	volatile bool running; // Más jelentést kéne neki adni és akkor egyértelműbb lenne, hogy mikor kell beállítani igazra/hamisra
-	pthread_t *threads;
-	int thread_num;
+	dns_db db; /** The database that holds the DNS records */
+	udp_socket_wp socket; /** Socket to listen to for the queries */
+	volatile bool running; /** Status flag if the server is still running */
+	pthread_t *threads; /** Ids of the threads started to serve the requets */
+	int thread_num; /** Number of the threads started */
 	dns_server(const dns_db& __db) { throw "Not implementable"; }
 protected:
+	/**
+	 * The function that can be started in a thread.
+	 * It calls serve_forever() on server_obj.
+	 * @param server_obj The server object prepared to serve requests
+	 * @return Nothing
+	 */
 	static void *thread_func(void *server_obj);
+
+	/**
+	 * Serves a single request.
+	 * Gets a query, and if there is a database hit, it sends back a response.
+	 */
 	void serve_one_request();
+
+	/**
+	 * Deletes the threads array.
+	 * It is only for avoidance of code duplication.
+	 */
 	void delete_threads();
 public:
 	dns_server();
@@ -31,16 +47,37 @@ public:
 	dns_server(const general_sockaddr_wp& addr, const char *db_path);
 	dns_server(const general_sockaddr_wp& addr, const dns_db& __db);
 
+	/**
+	 * Opens an sqlite database.
+	 * @param db_path Path to the sqlite database file.
+	 */
 	void connect_db(const char* db_path) { db.close(); db.open(db_path); }
 
+	/**
+	 * Binds the server to the sockaddr specified.
+	 * @param addr Sockaddr to bind to
+	 */
 	void init(const general_sockaddr_wp& addr);
 
+	/**
+	 * Serves requests one by one until running is set to false.
+	 */
 	void serve_forever();
+	/**
+	 * Starts to serve request in n different threads.
+	 */
 	void serve_in_threads(int n);
 
+	/**
+	 * Stops serving in all threads.
+	 */
 	void stop();
 
+	/**
+	 * Releases every required resource.
+	 */
 	void shutdown();
+
 	virtual ~dns_server() { this->shutdown(); }
 };
 
diff --git a/include/logger.h b/include/logger.h
index aca171b..7098c16 100644
--- a/include/logger.h
+++ b/include/logger.h
@@ -12,11 +12,38 @@
 #include <string.h>
 #include <errno.h>
 
+/**
+ * Defines the interface of a variable logging function.
+ * Implement this, and it will be compatible with all the logging used in this software.
+ */
 #define LOGGER_FUNCTION_HEADER(func_name) void (func_name)(int __pri, const char *__fmt, ...)
+
+/**
+ * On demand wrapper of perror.
+ * Some of the syscalls or libc functions set errno, but perror would always print to stderr.
+ * This macro makes it easy write perror messages to the variable log intervace.
+ */
 #define PERROR_ON_DEMAND(__s) log_on_demand(LOG_ERR, "%s: %s", __s, strerror(errno))
 
+/**
+ * Pointer to a variable logging function.
+ */
 typedef LOGGER_FUNCTION_HEADER(*logger);
 
+/**
+ * Logs to syslog.
+ * @param __pri Priority of the log message
+ * @param __fmt Format string
+ * @param ... Additional variable for format string
+ */
 LOGGER_FUNCTION_HEADER(syslog_on_demand);
+
+/**
+ * Logs to stderr.
+ * @param __pri Priority of the log message
+ * @param __fmt Format string
+ * @param ... Additional variable for format string
+ */
 LOGGER_FUNCTION_HEADER(stdlog_on_demand);
+
 #endif /* LOGGER_H */
diff --git a/include/record.h b/include/record.h
index ae341d5..58ff725 100644
--- a/include/record.h
+++ b/include/record.h
@@ -10,6 +10,9 @@
 
 #include <stdint.h>
 
+/**
+ * Represents a DNS record selected form the database.
+ */
 struct record
 {
 	char name[50] = { 0 };
diff --git a/include/udp_packet_wp.h b/include/udp_packet_wp.h
index c298524..8b47ea8 100644
--- a/include/udp_packet_wp.h
+++ b/include/udp_packet_wp.h
@@ -22,7 +22,7 @@ class udp_packet_wp
 protected:
 	void set_buf_len(const ssize_t new_buf_len);
 public:
-	general_sockaddr_wp address;
+	general_sockaddr_wp address; /** Source address of the packet */
 
 	udp_packet_wp();
 	udp_packet_wp(const udp_packet_wp& other);
diff --git a/src/IPC_US_communicator.cpp b/src/IPC_US_communicator.cpp
index 41e2f51..4f552a1 100644
--- a/src/IPC_US_communicator.cpp
+++ b/src/IPC_US_communicator.cpp
@@ -12,7 +12,7 @@
 
 #include "../include/IPC_US_communicator.h"
 
-IPC_US_communicator::IPC_US_communicator(std::string socket_path, const bool master): master(master), comm_sock(AF_UNIX) {
+IPC_US_communicator::IPC_US_communicator(std::string socket_path, const bool master): server(master), comm_sock(AF_UNIX) {
 	std::string master_sock_path = socket_path + "master.sock";
 	std::string slave_sock_path = socket_path + "slave.sock";
 
@@ -20,20 +20,20 @@ IPC_US_communicator::IPC_US_communicator(std::string socket_path, const bool mas
 	memset(&ipc, 0, sizeof(ipc));
 	ipc.sun_family = AF_UNIX;
 	strncpy(ipc.sun_path+1, master_sock_path.c_str(), sizeof(ipc.sun_path)-1-1);
-	this->master_sockaddr.set_sockaddr((sockaddr*) &ipc, sizeof(ipc));
+	this->server_sockaddr.set_sockaddr((sockaddr*) &ipc, sizeof(ipc));
 
 	strncpy(ipc.sun_path+1, slave_sock_path.c_str(), sizeof(ipc.sun_path)-1-1);
-	this->slave_sockaddr.set_sockaddr((sockaddr*) &ipc, sizeof(ipc));
+	this->controller_sockaddr.set_sockaddr((sockaddr*) &ipc, sizeof(ipc));
 
 	timeval timeout = { 5, 0 };
 	comm_sock.setsockopt_wp(SOL_SOCKET, SO_RCVTIMEO, &timeout, sizeof(timeout));
 	if(master)
 	{
-		comm_sock.bind_wp(master_sockaddr);
+		comm_sock.bind_wp(server_sockaddr);
 	}
 	else
 	{
-		comm_sock.bind_wp(slave_sockaddr);
+		comm_sock.bind_wp(controller_sockaddr);
 	}
 }
 
@@ -52,9 +52,9 @@ std::string IPC_US_communicator::recv_data() {
 
 void IPC_US_communicator::send_data(const std::string& data) {
 	general_sockaddr_wp pair_sockaddr;
-	if(master)
-		pair_sockaddr = slave_sockaddr;
+	if(server)
+		pair_sockaddr = controller_sockaddr;
 	else
-		pair_sockaddr = master_sockaddr;
+		pair_sockaddr = server_sockaddr;
 	comm_sock.sendto_wp(data.c_str(), data.length()+1, 0, pair_sockaddr);// +1: terminal '\0'
 }
-- 
GitLab