Cleanup and comment the code of network_server example.

Update issue 123
Status: FixedInGit

examples/network_server/client.c

@@ -23,9 +23,13 @@
 #include "fileproto.pb.h"
 #include "common.h"
 
+/* This callback function will be called once for each filename received
+ * from the server. The filenames will be printed out immediately, so that
+ * no memory has to be allocated for them.
+ */
 bool printfile_callback(pb_istream_t *stream, const pb_field_t *field, void **arg)
 {
-    FileInfo fileinfo;
+    FileInfo fileinfo = {};
     
     if (!pb_decode(stream, FileInfo_fields, &fileinfo))
         return false;
@@ -35,14 +39,20 @@ bool printfile_callback(pb_istream_t *stream, const pb_field_t *field, void **ar
     return true;
 }
 
+/* This function sends a request to socket 'fd' to list the files in
+ * directory given in 'path'. The results received from server will
+ * be printed to stdout.
+ */
 bool listdir(int fd, char *path)
 {
-    ListFilesRequest request;
+    /* Construct and send the request to server */
-    ListFilesResponse response;
+    {
-    pb_istream_t input = pb_istream_from_socket(fd);
+        ListFilesRequest request = {};
         pb_ostream_t output = pb_ostream_from_socket(fd);
         uint8_t zero = 0;
         
+        /* In our protocol, path is optional. If it is not given,
+         * the server will list the root directory. */
         if (path == NULL)
         {
             request.has_path = false;
@@ -59,15 +69,25 @@ bool listdir(int fd, char *path)
             strcpy(request.path, path);
         }
         
+        /* Encode the request. It is written to the socket immediately
+         * through our custom stream. */
         if (!pb_encode(&output, ListFilesRequest_fields, &request))
         {
-        fprintf(stderr, "Encoding failed.\n");
+            fprintf(stderr, "Encoding failed: %s\n", PB_GET_ERROR(&output));
             return false;
         }
         
         /* We signal the end of request with a 0 tag. */
         pb_write(&output, &zero, 1);
+    }
     
+    /* Read back the response from server */
+    {
+        ListFilesResponse response = {};
+        pb_istream_t input = pb_istream_from_socket(fd);
+        
+        /* Give a pointer to our callback function, which will handle the
+         * filenames as they arrive. */
         response.file.funcs.decode = &printfile_callback;
         
         if (!pb_decode(&input, ListFilesResponse_fields, &response))
@@ -76,11 +96,14 @@ bool listdir(int fd, char *path)
             return false;
         }
         
+        /* If the message from server decodes properly, but directory was
+         * not found on server side, we get path_error == true. */
         if (response.path_error)
         {
             fprintf(stderr, "Server reported error.\n");
             return false;
         }
+    }
     
     return true;
 }
@@ -96,6 +119,7 @@ int main(int argc, char **argv)
     
     sockfd = socket(AF_INET, SOCK_STREAM, 0);
     
+    /* Connect to server running on localhost:1234 */
     memset(&servaddr, 0, sizeof(servaddr));
     servaddr.sin_family = AF_INET;
     servaddr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
@@ -107,9 +131,11 @@ int main(int argc, char **argv)
         return 1;
     }
     
+    /* Send the directory listing request */
     if (!listdir(sockfd, path))
         return 2;
     
+    /* Close connection */
     close(sockfd);
     
     return 0;

examples/network_server/server.c

@@ -23,11 +23,16 @@
 #include "fileproto.pb.h"
 #include "common.h"
 
+/* This callback function will be called once during the encoding.
+ * It will write out any number of FileInfo entries, without consuming unnecessary memory.
+ * This is accomplished by fetching the filenames one at a time and encoding them
+ * immediately.
+ */
 bool listdir_callback(pb_ostream_t *stream, const pb_field_t *field, void * const *arg)
 {
     DIR *dir = (DIR*) *arg;
     struct dirent *file;
-    FileInfo fileinfo;
+    FileInfo fileinfo = {};
     
     while ((file = readdir(dir)) != NULL)
     {
@@ -35,9 +40,12 @@ bool listdir_callback(pb_ostream_t *stream, const pb_field_t *field, void * cons
         strncpy(fileinfo.name, file->d_name, sizeof(fileinfo.name));
         fileinfo.name[sizeof(fileinfo.name) - 1] = '\0';
         
+        /* This encodes the header for the field, based on the constant info
+         * from pb_field_t. */
         if (!pb_encode_tag_for_field(stream, field))
             return false;
         
+        /* This encodes the data for the field, based on our FileInfo structure. */
         if (!pb_encode_submessage(stream, FileInfo_fields, &fileinfo))
             return false;
     }
@@ -45,13 +53,18 @@ bool listdir_callback(pb_ostream_t *stream, const pb_field_t *field, void * cons
     return true;
 }
 
+/* Handle one arriving client connection.
+ * Clients are expected to send a ListFilesRequest, terminated by a '0'.
+ * Server will respond with a ListFilesResponse message.
+ */
 void handle_connection(int connfd)
 {
-    ListFilesRequest request;
+    DIR *directory = NULL;
-    ListFilesResponse response;
+    
+    /* Decode the message from the client and open the requested directory. */
+    {
+        ListFilesRequest request = {};
         pb_istream_t input = pb_istream_from_socket(connfd);
-    pb_ostream_t output = pb_ostream_from_socket(connfd);
-    DIR *directory;
         
         if (!pb_decode(&input, ListFilesRequest_fields, &request))
         {
@@ -60,19 +73,26 @@ void handle_connection(int connfd)
         }
         
         directory = opendir(request.path);
-    
         printf("Listing directory: %s\n", request.path);
+    }
+    
+    /* List the files in the directory and transmit the response to client */
+    {
+        ListFilesResponse response = {};
+        pb_ostream_t output = pb_ostream_from_socket(connfd);
         
         if (directory == NULL)
         {
             perror("opendir");
             
+            /* Directory was not found, transmit error status */
             response.has_path_error = true;
             response.path_error = true;
             response.file.funcs.encode = NULL;
         }
         else
         {
+            /* Directory was found, transmit filenames */
             response.has_path_error = false;
             response.file.funcs.encode = &listdir_callback;
             response.file.arg = directory;
@@ -80,18 +100,22 @@ void handle_connection(int connfd)
         
         if (!pb_encode(&output, ListFilesResponse_fields, &response))
         {
-        printf("Encoding failed.\n");
+            printf("Encoding failed: %s\n", PB_GET_ERROR(&output));
         }
     }
     
+    if (directory != NULL)
+        closedir(directory);
+}
+
 int main(int argc, char **argv)
 {
     int listenfd, connfd;
     struct sockaddr_in servaddr;
     int reuse = 1;
     
+    /* Listen on localhost:1234 for TCP connections */
     listenfd = socket(AF_INET, SOCK_STREAM, 0);
-    
     setsockopt(listenfd, SOL_SOCKET, SO_REUSEADDR, &reuse, sizeof(reuse));
     
     memset(&servaddr, 0, sizeof(servaddr));
@@ -112,6 +136,7 @@ int main(int argc, char **argv)
     
     for(;;)
     {
+        /* Wait for a client */
         connfd = accept(listenfd, NULL, NULL);
         
         if (connfd < 0)
@@ -128,4 +153,6 @@ int main(int argc, char **argv)
         
         close(connfd);
     }
+    
+    return 0;
 }