libt2n: (gerd) doxygenize

[libt2n] / src / socket_handler.cpp

diff --git a/src/socket_handler.cpp b/src/socket_handler.cpp
index 4fa27d0..2856adf 100644 (file)
--- a/src/socket_handler.cpp
+++ b/src/socket_handler.cpp
@@ -34,6 +34,7 @@
 #include <grp.h>
 
 #include <sstream>
+#include <iostream>
 
 #include "socket_handler.hxx"
 #include "t2n_exception.hxx"
@@ -43,6 +44,7 @@ using namespace std;
 namespace libt2n
 {
 
+/// set options like fast reuse and keepalive every socket should have
 void socket_handler::set_socket_options(int sock)
 {
     int i=1;
@@ -104,11 +106,28 @@ void socket_handler::set_socket_options(int sock)
     }
 }
 
+/// close the underlying socket connection. Don't call directly, use the version provided
+/// by the connection class you are using.
 void socket_handler::close()
 {
+    // graceful shutdown
+    shutdown(sock,SHUT_RDWR);
     ::close(sock);
 }
 
+/// is the underlying socket connection still open?
+bool socket_handler::is_closed()
+{
+    int r=fcntl(sock,F_GETFL);
+
+    return !(r & O_ACCMODE);
+}
+
+/** @brief check if new data is waiting on the raw socket
+    @param usec_timeout wait until new data is found, max timeout usecs.
+            -1: wait endless
+            NULL: no timeout
+*/
 bool socket_handler::data_waiting(long long usec_timeout)
 {
     // just our socket
@@ -137,15 +156,25 @@ bool socket_handler::data_waiting(long long usec_timeout)
         return false;
 }
 
+/** @brief read data from the raw socket and copy it into the provided buffer
+    @param buffer the buffer where to append the new data
+    @param usec_timeout wait until new data is found, max timeout usecs.
+            -1: wait endless
+            NULL: no timeout
+*/
 bool socket_handler::fill_buffer(std::string& buffer, long long usec_timeout)
 {
-    // fast path for timeout==-1
-    if (usec_timeout==-1 || data_waiting(usec_timeout))
+    // fast path for timeout==0
+    if (usec_timeout==0 || data_waiting(usec_timeout))
         return fill_buffer(buffer);
     else
         return false;
 }
 
+/** @brief read data from the raw socket and copy it into the provided buffer. Returns
+           instantly if no data is waiting.
+    @param buffer the buffer where to append the new data
+*/
 bool socket_handler::fill_buffer(std::string& buffer)
 {
     bool try_again=false;
@@ -182,7 +211,7 @@ bool socket_handler::fill_buffer(std::string& buffer)
         buffer.assign(socket_buffer,nbytes);
 
     // more data waiting -> recurse
-    if (data_waiting())
+    if (data_waiting(0))
         fill_buffer(buffer);
 
     if (nbytes > 0)
@@ -191,7 +220,9 @@ bool socket_handler::fill_buffer(std::string& buffer)
         return false;
 }
 
-void socket_handler::write(const std::string& data)
+/// writes raw data to the socket. Don't use directly, use the write() function provided by the 
+/// connection because it encapsulates the data.
+void socket_handler::socket_write(const std::string& data)
 {
     int offset = 0;
     while (offset < data.size())