frontend, proto: Include the response data type in query replies.

[sysdb.git] / src / include / frontend / proto.h

diff --git a/src/include/frontend/proto.h b/src/include/frontend/proto.h
index 1d549a933bad84f739611f0a61882e4e82e44735..c006c49afef15284c98d7da909b5654c8217952b 100644 (file)
--- a/src/include/frontend/proto.h
+++ b/src/include/frontend/proto.h
@@ -33,7 +33,7 @@ extern "C" {
 #endif
 
 /*
- * The SysDB frontend protocol is based messages being passed between the
+ * The SysDB frontend protocol is based on messages being passed between the
  * client and the server. Each message includes a header containing the
  * message type which is usually a status or command code, the length of the
  * message not including the header, and the message body. The content of the
@@ -53,15 +53,46 @@ extern "C" {
 typedef enum {
        /*
         * CONNECTION_OK:
-        * Indicates that a command was successful. The message body will contain
-        * the result of the command (if any) encoded as a JSON string.
+        * Indicates that a command was successful. The message body will usually
+        * be empty but may contain a string providing unformatted information
+        * providing more details.
+        *
+        * 0               32              64
+        * +---------------+---------------+
+        * | message type  | length        |
+        * +---------------+---------------+
+        * | optional status message ...   |
         */
        CONNECTION_OK = 0,
 
+       /*
+        * CONNECTION_DATA:
+        * Indicates that a data query was successful. The message body will
+        * contain the type of the data and the result encoded as a JSON string.
+        * The type is the same as the command code of the respective command (see
+        * below) and is stored as an unsigned 32bit integer in network
+        * byte-order. The result may be empty (but the type is still included).
+        *
+        * 0               32              64
+        * +---------------+---------------+
+        * | message type  | length        |
+        * +---------------+---------------+
+        * | result type   | result ...    |
+        * +---------------+               |
+        * | ...                           |
+        */
+       CONNECTION_DATA,
+
        /*
         * CONNECTION_ERROR:
         * Indicates that a command has failed. The message body will contain a
         * string describing the error.
+        *
+        * 0               32              64
+        * +---------------+---------------+
+        * | message type  | length        |
+        * +---------------+---------------+
+        * | error message ...             |
         */
        CONNECTION_ERROR,
 
@@ -70,6 +101,12 @@ typedef enum {
         * Indicates an asynchronous log message. The message body will contain
         * the message string providing informational or warning logs. Log
         * messages may be sent to the client any time.
+        *
+        * 0               32              64
+        * +---------------+---------------+
+        * | message type  | length        |
+        * +---------------+---------------+
+        * | log message ...               |
         */
        CONNECTION_LOG,
 } sdb_conn_status_t;
@@ -95,14 +132,20 @@ typedef enum {
         * username of the user contacting the server. The server may then send
         * further requests to the client for authentication (not implemented
         * yet). Once the setup and authentication was successful, the server
-        * replies with CONNECTION_OK. No other messages may be sent to the server
-        * before this. Also, the server does not send any asynchronous messages
-        * before startup is complete.
+        * replies with CONNECTION_OK. Further information may be requested from
+        * the server using special messages specific to the authentication
+        * method. The server does not send any asynchronous messages before
+        * startup is complete.
         */
        CONNECTION_STARTUP,
 
        /*
-        * Querying the server.
+        * Querying the server. On success, the server replies with
+        * CONNECTION_DATA.
+        *
+        * The command codes listed here are used, both, for sending a query to
+        * the server and to indicate the response type from a query in a DATA
+        * message.
         */
 
        /*