/*!
    \page jsonrpc.html
    \title JSON-RPC API
    \ingroup jsonrpc

    \brief The JSON RPC interface represents a socket connection using plaintext string communication.

    \chapter Description

    The JSON RPC interface represents a socket connection using plaintext string communication.
    Messages are exchanged using the JSON format. Please note that this is not a REST API as the
    transport channel is not based on HTTP. It is an internal RPC mechanism to allow communication
    between the guh Server and the main controller interface. This communication socket is not meant
    to be exported to the outside of the of the system as it allows arbitrary commands to manipulate
    the system.

    The JSON message protocol communicates by exchanging JSON Objects with the following properties:
    \list
        \li \code "id": integer \endcode
            The id should be a unique identifier for the message. Any server response will contain the
            same id allowing to match responses to requests/commands. This parameter is mandatory.
        \li \code "method": string \endcode
            The method field holds the method to be executed. Methods are grouped into namespaces. The
            method string consists of two parts, the namespace and the method name, separated by a dot.
            This parameter is mandatory.
            (Example: \c"JSONRPC.Introspect")
        \li \code "params": object \endcode
            The params contains any JSON object. This parameter is optional and differs according to
            the requested method.
    \endlist

    \chapter Handshake

    Once connected to the socket, the server will send immediatly a handshake message. The handshake message 
    is a JSON object and contains all relevant information about the server and the API in order to start 
    communicationg with the server.
    
    Here is an example of the handshare:
    
    \code
    {
        "id": 0,
        "name": "guh",
        "protocol version": "1.2",
        "authenticationRequired": false,
        "initialSetupRequired": false,
        "pushButtonAuthAvailable": false,
        "server": "guhIO",
        "language": "de_DE",
        "uuid": "{42842b0f-a7bb-4a94-b624-a55f31c5603e}",
        "version": "0.8.3"
    }
    \endcode


    \list
        \li \code "id": int \endcode
            The id in the handshake has always the value 0. This is the first message during connection.
        \li \code "name": string \endcode
            This field represents the name of the server you are connected to. This name is user defined an can be changed.
            (Example: \c"JSONRPC.Introspect")
        \li \code "protocol version": string \endcode
            The field represents the API version of the server you are connected to. This should be used for API compatibility checks
        \li \code "authenticationRequired": bool \endcode
            If this property is true, a client must perform the authentication process before beeing able to interact with the API. See section \l{Authentication} for more information. 
        \li \code "initialSetupRequired": bool \endcode
            This property indicates if the server was set up already. A server is set up if a user has been created. If the \tt authenticationRequired property is \tt{false}, this field can be ignored.
        \li \code "pushButtonAuthAvailable": bool \endcode
            This property indicates if the server has a running push-button agent and therefore the push-button authentication available. If the \tt authenticationRequired property is \tt{false}, this field can be ignored.
            \li \code "server": string \endcode
            This property holds the name of the server. This name can not be changed.   
        \li \code "language": string \endcode
            This property holds the language of the server. The language can be changed in the settings.
        \li \code "uuid": string \endcode
            This property holds the UUID of the server and can be used as a unique identifier.
        \li \code "version": string \endcode
            This property holds the build version of the server.
    \endlist


    \chapter Authentication
    
    The API has an authentication mechanism, which makes sure that no unauthorized network participent can perform actions or get information from the server. For using the authentication the \tt authenticationRequired property in the \l{Handshake}{handshake} must be \tt{true}.
    
    \section2 Create a user
    
    
    
    \section2 Authenticate 
    
    
    \chapter API
    \include jsonrpc-api.qdoc
    
    \section1 Newest JSON-RPC API
    
    \quotefile tests/auto/api.json
*/