index 2e82738449cd6a50826e22648e0dcd735167fca4..de45f736b02b310e69b6aac0e45cb4c530eb19fb 100644 (file)
#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
/* status codes returned to a client */
typedef enum {
+ /*
+ * Generic status and log messages.
+ */
+
/*
* 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_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,
/*
* CONNECTION_LOG:
* 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.
+ * the log priority (see utils/error.h) and message. Log messages may be
+ * sent to the client any time.
+ *
+ * 0 32 64
+ * +---------------+---------------+
+ * | message type | length |
+ * +---------------+---------------+
+ * | log priority | log message |
+ * +---------------+ |
+ * | ... |
*/
CONNECTION_LOG,
+
+ /*
+ * Query-result specific messages.
+ */
+
+ /*
+ * 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) if
+ * the query did not return any result. The type and the result message
+ * are empty on empty commands.
+ *
+ * 0 32 64
+ * +---------------+---------------+
+ * | message type | length |
+ * +---------------+---------------+
+ * | result type | result ... |
+ * +---------------+ |
+ * | ... |
+ */
+ CONNECTION_DATA = 100,
} sdb_conn_status_t;
/* accepted commands / state of the connection */
* 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.
+ * 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.
*/
/*
/*
* CONNECTION_LIST:
- * Execute the 'LIST' command in the server.
+ * Execute the 'LIST' command in the server. The message body may include
+ * the type of the objects to be included in addition to all hosts,
+ * encoded as a 32bit integer in network byte-order.
*/
CONNECTION_LIST,
* CONNECTION_EXPR:
* A parsed expression. Only used internally.
*/
- CONNECTION_EXPR,
+ CONNECTION_EXPR = 100,
} sdb_conn_state_t;
#ifdef __cplusplus